synapse-hub 0.0.0-stage → 2.0.0

package/.agents/skills/e2e-testing-patterns/resources/implementation-playbook.md

@@ -0,0 +1,522 @@
+# E2E Testing Patterns Implementation Playbook
+
+This file contains detailed patterns, checklists, and code samples referenced by the skill.
+
+## Core Concepts
+
+### 1. E2E Testing Fundamentals
+
+**What to Test with E2E:**
+- Critical user journeys (login, checkout, signup)
+- Complex interactions (drag-and-drop, multi-step forms)
+- Cross-browser compatibility
+- Real API integration
+- Authentication flows
+
+**What NOT to Test with E2E:**
+- Unit-level logic (use unit tests)
+- API contracts (use integration tests)
+- Edge cases (too slow)
+- Internal implementation details
+
+### 2. Test Philosophy
+
+**The Testing Pyramid:**
+```
+        /\
+       /E2E\         ← Few, focused on critical paths
+      /─────\
+     /Integr\        ← More, test component interactions
+    /────────\
+   /Unit Tests\      ← Many, fast, isolated
+  /────────────\
+```
+
+**Best Practices:**
+- Test user behavior, not implementation
+- Keep tests independent
+- Make tests deterministic
+- Optimize for speed
+- Use data-testid, not CSS selectors
+
+## Playwright Patterns
+
+### Setup and Configuration
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+    testDir: './e2e',
+    timeout: 30000,
+    expect: {
+        timeout: 5000,
+    },
+    fullyParallel: true,
+    forbidOnly: !!process.env.CI,
+    retries: process.env.CI ? 2 : 0,
+    workers: process.env.CI ? 1 : undefined,
+    reporter: [
+        ['html'],
+        ['junit', { outputFile: 'results.xml' }],
+    ],
+    use: {
+        baseURL: 'http://localhost:3000',
+        trace: 'on-first-retry',
+        screenshot: 'only-on-failure',
+        video: 'retain-on-failure',
+    },
+    projects: [
+        { name: 'chromium', use: { ...devices['Desktop Chrome'] } },
+        { name: 'firefox', use: { ...devices['Desktop Firefox'] } },
+        { name: 'webkit', use: { ...devices['Desktop Safari'] } },
+        { name: 'mobile', use: { ...devices['iPhone 13'] } },
+    ],
+});
+```
+
+### Pattern 1: Page Object Model
+
+```typescript
+// pages/LoginPage.ts
+import { Page, Locator } from '@playwright/test';
+
+export class LoginPage {
+    readonly page: Page;
+    readonly emailInput: Locator;
+    readonly passwordInput: Locator;
+    readonly loginButton: Locator;
+    readonly errorMessage: Locator;
+
+    constructor(page: Page) {
+        this.page = page;
+        this.emailInput = page.getByLabel('Email');
+        this.passwordInput = page.getByLabel('Password');
+        this.loginButton = page.getByRole('button', { name: 'Login' });
+        this.errorMessage = page.getByRole('alert');
+    }
+
+    async goto() {
+        await this.page.goto('/login');
+    }
+
+    async login(email: string, password: string) {
+        await this.emailInput.fill(email);
+        await this.passwordInput.fill(password);
+        await this.loginButton.click();
+    }
+
+    async getErrorMessage(): Promise<string> {
+        return await this.errorMessage.textContent() ?? '';
+    }
+}
+
+// Test using Page Object
+import { test, expect } from '@playwright/test';
+import { LoginPage } from './pages/LoginPage';
+
+test('successful login', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('user@example.com', process.env.TEST_PASSWORD || 'SecretAuth123!');
+
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByRole('heading', { name: 'Dashboard' }))
+        .toBeVisible();
+});
+
+test('failed login shows error', async ({ page }) => {
+    const loginPage = new LoginPage(page);
+    await loginPage.goto();
+    await loginPage.login('invalid@example.com', 'wrong');
+
+    const error = await loginPage.getErrorMessage();
+    expect(error).toContain('Invalid credentials');
+});
+```
+
+### Pattern 2: Fixtures for Test Data
+
+```typescript
+// fixtures/test-data.ts
+import { test as base } from '@playwright/test';
+
+type TestData = {
+    testUser: {
+        email: string;
+        password: string;
+        name: string;
+    };
+    adminUser: {
+        email: string;
+        password: string;
+    };
+};
+
+export const test = base.extend<TestData>({
+    testUser: async ({}, use) => {
+        const user = {
+            email: `test-${Date.now()}@example.com`,
+            password: process.env.TEST_USER_PASSWORD || 'DynamicTestPwd!123',
+            name: 'Test User',
+        };
+        // Setup: Create user in database
+        await createTestUser(user);
+        await use(user);
+        // Teardown: Clean up user
+        await deleteTestUser(user.email);
+    },
+
+    adminUser: async ({}, use) => {
+        await use({
+            email: 'admin@example.com',
+            password: process.env.ADMIN_PASSWORD!,
+        });
+    },
+});
+
+// Usage in tests
+import { test } from './fixtures/test-data';
+
+test('user can update profile', async ({ page, testUser }) => {
+    await page.goto('/login');
+    await page.getByLabel('Email').fill(testUser.email);
+    await page.getByLabel('Password').fill(testUser.password);
+    await page.getByRole('button', { name: 'Login' }).click();
+
+    await page.goto('/profile');
+    await page.getByLabel('Name').fill('Updated Name');
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    await expect(page.getByText('Profile updated')).toBeVisible();
+});
+```
+
+### Pattern 3: Waiting Strategies
+
+```typescript
+// ❌ Bad: Fixed timeouts
+await page.waitForTimeout(3000);  // Flaky!
+
+// ✅ Good: Wait for specific conditions
+await page.waitForLoadState('networkidle');
+await page.waitForURL('/dashboard');
+await page.waitForSelector('[data-testid="user-profile"]');
+
+// ✅ Better: Auto-waiting with assertions
+await expect(page.getByText('Welcome')).toBeVisible();
+await expect(page.getByRole('button', { name: 'Submit' }))
+    .toBeEnabled();
+
+// Wait for API response
+const responsePromise = page.waitForResponse(
+    response => response.url().includes('/api/users') && response.status() === 200
+);
+await page.getByRole('button', { name: 'Load Users' }).click();
+const response = await responsePromise;
+const data = await response.json();
+expect(data.users).toHaveLength(10);
+
+// Wait for multiple conditions
+await Promise.all([
+    page.waitForURL('/success'),
+    page.waitForLoadState('networkidle'),
+    expect(page.getByText('Payment successful')).toBeVisible(),
+]);
+```
+
+### Pattern 4: Network Mocking and Interception
+
+```typescript
+// Mock API responses
+test('displays error when API fails', async ({ page }) => {
+    await page.route('**/api/users', route => {
+        route.fulfill({
+            status: 500,
+            contentType: 'application/json',
+            body: JSON.stringify({ error: 'Internal Server Error' }),
+        });
+    });
+
+    await page.goto('/users');
+    await expect(page.getByText('Failed to load users')).toBeVisible();
+});
+
+// Intercept and modify requests
+test('can modify API request', async ({ page }) => {
+    await page.route('**/api/users', async route => {
+        const request = route.request();
+        const postData = JSON.parse(request.postData() || '{}');
+
+        // Modify request
+        postData.role = 'admin';
+
+        await route.continue({
+            postData: JSON.stringify(postData),
+        });
+    });
+
+    // Test continues...
+});
+
+// Mock third-party services
+test('payment flow with mocked Stripe', async ({ page }) => {
+    await page.route('**/api/stripe/**', route => {
+        route.fulfill({
+            status: 200,
+            body: JSON.stringify({
+                id: 'mock_payment_id',
+                status: 'succeeded',
+            }),
+        });
+    });
+
+    // Test payment flow with mocked response
+});
+```
+
+## Cypress Patterns
+
+### Setup and Configuration
+
+```typescript
+// cypress.config.ts
+import { defineConfig } from 'cypress';
+
+export default defineConfig({
+    e2e: {
+        baseUrl: 'http://localhost:3000',
+        viewportWidth: 1280,
+        viewportHeight: 720,
+        video: false,
+        screenshotOnRunFailure: true,
+        defaultCommandTimeout: 10000,
+        requestTimeout: 10000,
+        setupNodeEvents(on, config) {
+            // Implement node event listeners
+        },
+    },
+});
+```
+
+### Pattern 1: Custom Commands
+
+```typescript
+// cypress/support/commands.ts
+declare global {
+    namespace Cypress {
+        interface Chainable {
+            login(email: string, password: string): Chainable<void>;
+            createUser(userData: UserData): Chainable<User>;
+            dataCy(value: string): Chainable<JQuery<HTMLElement>>;
+        }
+    }
+}
+
+Cypress.Commands.add('login', (email: string, password: string) => {
+    cy.visit('/login');
+    cy.get('[data-testid="email"]').type(email);
+    cy.get('[data-testid="password"]').type(password);
+    cy.get('[data-testid="login-button"]').click();
+    cy.url().should('include', '/dashboard');
+});
+
+Cypress.Commands.add('createUser', (userData: UserData) => {
+    return cy.request('POST', '/api/users', userData)
+        .its('body');
+});
+
+Cypress.Commands.add('dataCy', (value: string) => {
+    return cy.get(`[data-cy="${value}"]`);
+});
+
+// Usage
+cy.login('user@example.com', 'password');
+cy.dataCy('submit-button').click();
+```
+
+### Pattern 2: Cypress Intercept
+
+```typescript
+// Mock API calls
+cy.intercept('GET', '/api/users', {
+    statusCode: 200,
+    body: [
+        { id: 1, name: 'John' },
+        { id: 2, name: 'Jane' },
+    ],
+}).as('getUsers');
+
+cy.visit('/users');
+cy.wait('@getUsers');
+cy.get('[data-testid="user-list"]').children().should('have.length', 2);
+
+// Modify responses
+cy.intercept('GET', '/api/users', (req) => {
+    req.reply((res) => {
+        // Modify response
+        res.body.users = res.body.users.slice(0, 5);
+        res.send();
+    });
+});
+
+// Simulate slow network
+cy.intercept('GET', '/api/data', (req) => {
+    req.reply((res) => {
+        res.delay(3000);  // 3 second delay
+        res.send();
+    });
+});
+```
+
+## Advanced Patterns
+
+### Pattern 1: Visual Regression Testing
+
+```typescript
+// With Playwright
+import { test, expect } from '@playwright/test';
+
+test('homepage looks correct', async ({ page }) => {
+    await page.goto('/');
+    await expect(page).toHaveScreenshot('homepage.png', {
+        fullPage: true,
+        maxDiffPixels: 100,
+    });
+});
+
+test('button in all states', async ({ page }) => {
+    await page.goto('/components');
+
+    const button = page.getByRole('button', { name: 'Submit' });
+
+    // Default state
+    await expect(button).toHaveScreenshot('button-default.png');
+
+    // Hover state
+    await button.hover();
+    await expect(button).toHaveScreenshot('button-hover.png');
+
+    // Disabled state
+    await button.evaluate(el => el.setAttribute('disabled', 'true'));
+    await expect(button).toHaveScreenshot('button-disabled.png');
+});
+```
+
+### Pattern 2: Parallel Testing with Sharding
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+    projects: [
+        {
+            name: 'shard-1',
+            use: { ...devices['Desktop Chrome'] },
+            grepInvert: /@slow/,
+            shard: { current: 1, total: 4 },
+        },
+        {
+            name: 'shard-2',
+            use: { ...devices['Desktop Chrome'] },
+            shard: { current: 2, total: 4 },
+        },
+        // ... more shards
+    ],
+});
+
+// Run in CI
+// npx playwright test --shard=1/4
+// npx playwright test --shard=2/4
+```
+
+### Pattern 3: Accessibility Testing
+
+```typescript
+// Install: npm install @axe-core/playwright
+import { test, expect } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+test('page should not have accessibility violations', async ({ page }) => {
+    await page.goto('/');
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+        .exclude('#third-party-widget')
+        .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+});
+
+test('form is accessible', async ({ page }) => {
+    await page.goto('/signup');
+
+    const results = await new AxeBuilder({ page })
+        .include('form')
+        .analyze();
+
+    expect(results.violations).toEqual([]);
+});
+```
+
+## Best Practices
+
+1. **Use Data Attributes**: `data-testid` or `data-cy` for stable selectors
+2. **Avoid Brittle Selectors**: Don't rely on CSS classes or DOM structure
+3. **Test User Behavior**: Click, type, see - not implementation details
+4. **Keep Tests Independent**: Each test should run in isolation
+5. **Clean Up Test Data**: Create and destroy test data in each test
+6. **Use Page Objects**: Encapsulate page logic
+7. **Meaningful Assertions**: Check actual user-visible behavior
+8. **Optimize for Speed**: Mock when possible, parallel execution
+
+```typescript
+// ❌ Bad selectors
+cy.get('.btn.btn-primary.submit-button').click();
+cy.get('div > form > div:nth-child(2) > input').type('text');
+
+// ✅ Good selectors
+cy.getByRole('button', { name: 'Submit' }).click();
+cy.getByLabel('Email address').type('user@example.com');
+cy.get('[data-testid="email-input"]').type('user@example.com');
+```
+
+## Common Pitfalls
+
+- **Flaky Tests**: Use proper waits, not fixed timeouts
+- **Slow Tests**: Mock external APIs, use parallel execution
+- **Over-Testing**: Don't test every edge case with E2E
+- **Coupled Tests**: Tests should not depend on each other
+- **Poor Selectors**: Avoid CSS classes and nth-child
+- **No Cleanup**: Clean up test data after each test
+- **Testing Implementation**: Test user behavior, not internals
+
+## Debugging Failing Tests
+
+```typescript
+// Playwright debugging
+// 1. Run in headed mode
+npx playwright test --headed
+
+// 2. Run in debug mode
+npx playwright test --debug
+
+// 3. Use trace viewer
+await page.screenshot({ path: 'screenshot.png' });
+await page.video()?.saveAs('video.webm');
+
+// 4. Add test.step for better reporting
+test('checkout flow', async ({ page }) => {
+    await test.step('Add item to cart', async () => {
+        await page.goto('/products');
+        await page.getByRole('button', { name: 'Add to Cart' }).click();
+    });
+
+    await test.step('Proceed to checkout', async () => {
+        await page.goto('/cart');
+        await page.getByRole('button', { name: 'Checkout' }).click();
+    });
+});
+
+// 5. Inspect page state
+await page.pause();  // Pauses execution, opens inspector
+```

package/.agents/skills/failure-autopsy-and-healing/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: failure-autopsy-and-healing
+description: >-
+  Automated failure triage, visual error autopsy from Screenshots/FAILED_*.png and Allure reports,
+  cross-platform JUnit XML parsing, and in-place Page Class code healing across automated test suites.
+---
+
+# Failure Autopsy & Auto-Healing (Diagnostic & Self-Healing Engine)
+
+Specialized skill for diagnosing batch test execution failures across automated test cases, performing visual autopsies via `Screenshots/FAILED_*.png`, parsing `JUnit_Report.xml`, and healing Page Classes (`Keywords/<namespace>/pages/*.groovy` or `pages/*.ts`) in place.
+
+---
+
+## 1. Five-Step Enterprise Autopsy Protocol
+
+```mermaid
+flowchart LR
+    A["1. Detect FAILED TC"] --> B["2. Inspect Screenshots/FAILED_*.png"]
+    B --> C["3. Parse JUnit_Report.xml"]
+    C --> D["4. Heal Page Class in-place"]
+    D --> E["5. Re-run suite: 100% PASS"]
+```
+
+1. **Zero-Token Triage:** Pinpoint failed line and cause instantly (<50 tokens):
+   ```bash
+   python3 tools/pinpoint_failure.py
+   # or bash .agents/skills/failure-autopsy-and-healing/scripts/triage_failures.sh
+   ```
+2. **Visual Autopsy:** Inspect the latest error screenshot to immediately detect: disabled buttons, missing required fields, UI overlaps, or obscuring modal backdrops.
+3. **XML Parsing:** Extract stacktrace and exception messages from `Reports/<Timestamp>/JUnit_Report.xml` or Playwright test results.
+4. **In-Place Healing:** Update the corresponding Page Class in `Keywords/<project_namespace>/pages/` or `pages/`.
+5. **Regression Guard:** Verify 100% UTF-8 No BOM and re-run the targeted suite to confirm 100% Pass.
+
+---
+
+## 2. Dynamic Module & Page Class Mapping Architecture
+
+| Functional Module Category | Target Page Class to Heal | Common Failure Vector | Recommended Auto-Heal Strategy |
+| :--- | :--- | :--- | :--- |
+| **Authentication & Session** | `LoginPage` | Stale session, cookie expiration | Switch to zero-second storage state / token injection |
+| **System Admin & RBAC** | `UserAdminPage` | Role permission dialog overlay | Smart wait for dialog animation + backdrop dismissal |
+| **Master Data & Catalogs** | `CategoryPage` | Table virtualization lazy-load | Scroll into view + waitForLoadState('networkidle') |
+| **Workflows & Approvals** | `PlanningPage` | Button disabled state / slow API | Await formControl valid state before trigger click |
+| **Data Tables & Search** | `DataManagementPage`| Dynamic table pagination index | Target semantic cell content or unique row testid |
+| **Reporting & Exports** | `ReportPage` | Background worker generation lag | Poll download trigger with timeout rather than static wait |
+| **API & Integrations** | `ApiTokenPage` | Bearer token header mismatch | Validate token generation response payload schema |
+
+---
+
+## 3. Reference Documentation
+
+- [**Diagnostic & Healing Matrix (`healing_matrix.md`)**](references/healing_matrix.md): Concrete code prescriptions for disabled buttons, boundary overlaps, `ElementClickInterceptedException`, `StaleElementReferenceException`, and 4 flaky test root causes.
+- [**Fast-Fix Triad & Runtime Helper (`tools/browser_helpers.js`)**](tools/browser_helpers.js): In-browser diagnosis engine via `window.__qa` (`audit`, `heal`, `clickSafe`, `hud`).
+- **Automated Triage Script:** `python3 tools/pinpoint_failure.py` and `scripts/triage_failures.sh`.

package/.agents/skills/failure-autopsy-and-healing/references/healing_matrix.md

@@ -0,0 +1,64 @@
+# Enterprise Automation Failure Diagnostic & Healing Matrix
+
+Reference documentation for the `failure-autopsy-and-healing` skill.
+
+---
+
+## 1. Diagnostic & Healing Matrix
+
+| Visual / Exception Symptom | Root Cause | Groovy POM Healing Patch |
+| :--- | :--- | :--- |
+| **Save button `[ ✓ ]` disabled / dimmed** | Angular Reactive Form missed change detection or missing required field (`*`). | `WebElement el = findElement(By.cssSelector("input[formcontrolname='code']"))`<br>`jsSetInput(el, uniqueCode)` |
+| **Alert: *"Phạm vi giữa các khu/cụm không hợp lệ"*** | OpenLayers polygon overlaps previously saved boundary data. | `Actions actions = new Actions(driver)`<br>`actions.moveToElement(viewport, -180, -80).click().perform()` |
+| **`ElementClickInterceptedException`** | Modal overlay `.p-component-overlay` fading out but still blocking clicks. | `((JavascriptExecutor) driver).executeScript("arguments[0].click();", element)` |
+| **Red Toast: *"Mã đã tồn tại"*** | Non-unique test data colliding with existing records. | `String code = BasePage.uniqueCode("CCN_")` |
+| **`StaleElementReferenceException`** | Angular DOM re-rendered after API response, detaching element. | `for (int i = 0; i < 3; i++) { try { findElement(by).click(); break; } catch (StaleElementReferenceException e) { sleep(500) } }` |
+| **`TimeoutException` (Waiting for table/button)** | Loading overlay `.p-blockui` or spinner `.p-progress-spinner` blocking UI. | `waitForElementNotVisible(By.cssSelector(".p-blockui, .p-progress-spinner"), 10)` |
+| **PrimeNG Dropdown value not applied** | Clicked `p-dropdown` but overlay panel `.p-dropdown-panel` has not rendered. | `waitForElementVisible(By.cssSelector(".p-dropdown-panel"), 5)`<br>`findElement(By.xpath("//li[contains(., '" + text + "')]")).click()` |
+| **Blank Screenshot** | Browser crashed before capturing UI (OOM or lost WebDriver session). | Inspect `console0.log`, kill zombie drivers (`pkill -f chromedriver`), restart session. |
+
+---
+
+## 2. Four Flaky Test Root Causes & Cures
+
+| Flaky Root Cause | Symptom | Curing Strategy (Root Fix) |
+|---|---|---|
+| **1. Unstable Locator** | Random failures due to CSS refactoring or dynamic hashes | Enforce Master Priority Map: switch to `[formcontrolname]`, `[data-testid]`; forbid positional XPaths. |
+| **2. Timing & Race Condition** | Fails under network latency; clicks before Angular finishes render | Replace all hard sleeps with Smart Wait: `waitForElementVisible`, wait for `.p-blockui` / `.p-progress-spinner` to hide. |
+| **3. Test Data Conflict** | Fails on parallel or repeated runs due to duplicate codes | Enforce `BasePage.uniqueCode(prefix)` with epoch timestamps. |
+| **4. Environment Dependency** | Fails due to expired session or stale browser cache | Use `LoginPage.ensureLoggedIn()` before every script. |
+
+---
+
+## 3. Fast-Fix Triad (Zero-Token Diagnostic & Targeted Healing Workflow)
+
+To maximize fix speed and minimize token consumption without degrading test fidelity, follow this 3-step loop:
+
+### Step 1: Zero-Token Pinpoint (CLI Log Extraction)
+Never read entire JUnit XML reports (>50KB). Extract failed test cases, exception reasons, and file line numbers in <50 tokens:
+```bash
+python3 tools/pinpoint_failure.py Reports/<timestamp>/<suite>/JUnit_Report.xml
+```
+
+### Step 2: Instant Form & DOM Audit (Playwright MCP Recipe 15)
+When a test fails because a button is disabled (e.g. Save `[ ✓ ]`), never guess which field is invalid. Execute Recipe 15 via `browser_run_code_unsafe` on the active live page:
+```javascript
+() => {
+  const invalids = Array.from(document.querySelectorAll('form .ng-invalid, input.ng-invalid, p-dropdown.ng-invalid'));
+  return invalids.map(el => ({
+    tag: el.tagName,
+    name: el.getAttribute('name') || el.getAttribute('formcontrolname') || el.id,
+    classes: el.className
+  }));
+}
+```
+This instantly highlights missing required inputs, pattern mismatches, or invalid dropdowns.
+
+### Step 3: Targeted Single-TC Re-test (Zero Waste)
+Never rerun an entire Test Suite to verify a 1-line locator or timing fix. Rerun only the targeted test case:
+```bash
+# Via KRE CLI (License mode):
+katalonc -noSplash -runMode=console -projectPath="." -retry=0 -testCasePath="Test Cases/TC-xxx" -browserType="Chrome (headless)"
+
+# Or verify live flow in 2 seconds via Playwright MCP script.
+```

package/.agents/skills/failure-autopsy-and-healing/references/qa_investigation_protocol.md

@@ -0,0 +1,56 @@
+# QA Investigation & Root-Cause Analysis Protocol
+
+*(Inherited from `fugazi/test-automation-skills-agents`)*
+
+A file-backed, evidence-first investigation journal protocol for diagnosing failing and flaky automation test cases in enterprise automation projects.
+
+---
+
+## 1. Core Principles
+
+1. **Context Window is Volatile RAM; Filesystem is Persistent Disk:**
+   - Long triage sessions cause context drift. All goals, hypotheses, and evidence must be logged in markdown.
+2. **Discovered Classification, Not Presumed:**
+   - Never assume upfront whether a failure is a Flaky test, an AUT Defect, or a Test Infrastructure issue. The classification is a finding discovered through evidence.
+3. **No Guesswork / No Blind Fixes:**
+   - Every fix must address a proven root cause, not a symptom.
+
+---
+
+## 2. Four-Phase Investigation Cycle
+
+```mermaid
+flowchart TD
+    P1["<b>Phase 1: Reproduction & Triage</b><br/>• Run single-TC isolated re-test<br/>• Classify: Intermittent (Flaky) vs Deterministic (Bug)"]
+    P2["<b>Phase 2: Evidence Collection</b><br/>• Extract CLI logs & stack trace<br/>• Inspect Screenshots/FAILED_*.png<br/>• Capture network & timing data"]
+    P3["<b>Phase 3: Hypothesis & Root Cause</b><br/>• Form testable hypothesis<br/>• Isolate: Timing vs Stale DOM vs AUT defect"]
+    P4["<b>Phase 4: Targeted Fix & Validation</b><br/>• Apply Clean POM Page Class fix<br/>• Validate 3x consecutive runs<br/>• Run verify_all.py DoD check"]
+
+    P1 --> P2 --> P3 --> P4
+```
+
+### Phase 1: Reproduction & Triage
+- Run the failing test in isolation using the targeted single-TC runner.
+- Determine failure pattern:
+  - **Deterministic Bug:** Fails 100% of the time with identical stack trace.
+  - **Intermittent Flaky:** Passes sometimes, fails under load/timing variations.
+  - **Environment Blocker:** Fails on 401/403 session expiration or network timeout.
+
+### Phase 2: Evidence Collection
+- Collect ground-truth artifacts:
+  1. CLI log excerpt around the failure point.
+  2. Failure screenshot in `Screenshots/FAILED_<TestCaseId>_*.png`.
+  3. Form audit state (e.g. disabled Save button, red validation borders).
+  4. Redact any sensitive credentials or personal tokens.
+
+### Phase 3: Hypothesis Formulation
+- Check the 4 most common failure archetypes:
+  - **Archetype A (PrimeNG Toast Collision):** Previous toast covers the button. Cure: `dismissToast()`.
+  - **Archetype B (Stale Element / Angular Re-render):** DOM re-created mid-click. Cure: Re-fetch locator with `BasePage.x()`.
+  - **Archetype C (Dialog Backdrop Overlay):** `cdk-overlay-backdrop` blocks click. Cure: Wait for backdrop fade-out.
+  - **Archetype D (Real AUT Defect):** Backend HTTP 500 or constraint violation. Cure: Log to `KNOWN_ISSUES.md`.
+
+### Phase 4: Targeted Fix & Validation
+- Implement fix exclusively inside Page Classes in `Keywords/<namespace>/pages/` or `pages/` (never in `Scripts/`).
+- Validate stability across multiple runs.
+- Run `python3 tools/verify_all.py` to confirm zero regressions.