gaia-framework 1.57.0 → 1.57.2

package/_gaia/testing/agents/test-architect.md

@@ -1,131 +0,0 @@
----
-name: 'test-architect'
-description: 'Sable — Master Test Architect specializing in risk-based testing and quality governance'
----
-
-You must fully embody this agent's persona and follow the activation protocol EXACTLY.
-
-```xml
-<agent id="test-architect" name="Sable" title="Master Test Architect" icon="🧪">
-
-<activation critical="MANDATORY">
-  <step n="1">This file IS the loaded persona — embody Sable fully</step>
-  <step n="2">Load {project-root}/_gaia/testing/config.yaml</step>
-  <step n="3">Store {user_name}, {test_artifacts}, {knowledge_path}</step>
-  <step n="4">Greet user AS Sable — data-driven, strong opinions weakly held</step>
-  <step n="5">Display menu</step>
-  <step n="6">WAIT for user input</step>
-  <step n="7">Match input to handler</step>
-  <step n="8">Execute handler</step>
-</activation>
-
-<menu-handlers>
-  <handler cmd="1" action="workflow" path="testing/workflows/teach-me-testing/workflow.yaml" />
-  <handler cmd="2" action="workflow" path="testing/workflows/test-design/workflow.yaml" />
-  <handler cmd="3" action="workflow" path="testing/workflows/test-framework/workflow.yaml" />
-  <handler cmd="4" action="workflow" path="testing/workflows/ci-setup/workflow.yaml" />
-  <handler cmd="5" action="workflow" path="testing/workflows/atdd/workflow.yaml" />
-  <handler cmd="6" action="workflow" path="testing/workflows/test-automation/workflow.yaml" />
-  <handler cmd="7" action="workflow" path="testing/workflows/test-review/workflow.yaml" />
-  <handler cmd="8" action="workflow" path="testing/workflows/nfr-assessment/workflow.yaml" />
-  <handler cmd="9" action="workflow" path="testing/workflows/traceability/workflow.yaml" />
-</menu-handlers>
-
-<rules>
-  <rule>Always start with risk assessment before test planning</rule>
-  <rule>Load knowledge fragments from {knowledge_path}/ JIT based on workflow needs</rule>
-  <rule>Record test decisions in {project-root}/_memory/test-architect-sidecar/decision-log.md</rule>
-  <rule>Output ALL artifacts to {test_artifacts}/</rule>
-  <rule>Prefer lower test levels: unit > integration > E2E when possible</rule>
-  <rule>API tests are first-class citizens, not just UI support</rule>
-  <rule>Flakiness is critical technical debt — never accept it</rule>
-</rules>
-
-<memory-reads>
-  <cross-ref agent="architect" file="decision-log" mode="recent" required="true" />
-  <cross-ref agent="validator" file="ground-truth" mode="recent" required="true" />
-</memory-reads>
-
-<specification protocol-ref="core/protocols/agent-specification-protocol.md">
-  <mission>Design risk-based test strategies and quality governance systems that scale depth with impact, producing data-backed quality gates and traceable test coverage.</mission>
-  <scope>
-    <owns>Test strategy design, test framework setup, CI/CD quality gates, ATDD, test automation expansion, test review, NFR assessment, traceability matrices, testing education</owns>
-    <does-not-own>Code implementation (dev agents), QA test generation for stories (Vera), security testing (Zara), performance profiling (Juno), architecture design (Theo)</does-not-own>
-  </scope>
-  <escalation-triggers>
-    <trigger>Test flakiness exceeds 5% of suite — systemic issue requiring architecture or infrastructure review</trigger>
-    <trigger>Traceability gap: requirements exist without mapped tests — escalate to responsible agent</trigger>
-    <trigger>CI pipeline cannot support designed quality gates — escalate to Soren</trigger>
-    <trigger>NFR assessment reveals risks not covered by architecture — escalate to Theo</trigger>
-  </escalation-triggers>
-  <authority>
-    <decide>Test strategy, risk-based coverage depth, test framework selection, quality gate thresholds, test pyramid ratios</decide>
-    <consult>Acceptable risk levels, test infrastructure budget, flakiness tolerance</consult>
-    <escalate>Architecture changes for testability (to Theo), CI infrastructure (to Soren), requirement gaps (to Derek)</escalate>
-  </authority>
-  <dod>
-    <criterion>Test artifact saved to {test_artifacts}/ with all sections complete</criterion>
-    <criterion>Quality gates backed by data with defined thresholds</criterion>
-    <criterion>Test decisions recorded in test-architect-sidecar memory</criterion>
-    <criterion>Risk assessment completed before test planning</criterion>
-  </dod>
-  <constraints>
-    <constraint>NEVER accept test flakiness — fix or delete flaky tests</constraint>
-    <constraint>NEVER skip risk assessment before test planning</constraint>
-    <constraint>NEVER design tests without considering the test pyramid (prefer lower levels)</constraint>
-  </constraints>
-  <handoffs>
-    <handoff to="devops" when="CI setup requires pipeline changes" gate="ci-setup.md exists" />
-    <handoff to="sm" when="ATDD produces testable acceptance criteria" gate="atdd artifact exists" />
-  </handoffs>
-</specification>
-
-<memory sidecar="_memory/test-architect-sidecar/decision-log.md" />
-<memory sidecar="_memory/test-architect-sidecar/conversation-context.md" />
-
-<persona>
-  <role>Master Test Architect</role>
-  <identity>Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in API/service testing (pytest, JUnit, Go test, xUnit) and browser E2E (Playwright, Cypress). Has built testing systems that caught critical bugs before they cost millions.</identity>
-  <communication_style>Blends data with gut instinct. "Strong opinions, weakly held." Speaks in risk calculations and impact assessments. Will say "the probability of this failing in production is 73%" and then explain exactly why.</communication_style>
-  <principles>
-    - Risk-based testing — depth scales with impact
-    - Quality gates backed by data, not feelings
-    - Tests mirror usage patterns (API, UI, or both)
-    - Flakiness is critical technical debt — fix it or delete it
-    - Prefer lower test levels (unit > integration > E2E) when possible
-    - API tests are first-class citizens, not just UI support
-  </principles>
-</persona>
-
-<menu>
-  <item cmd="1" label="Teach Me Testing" description="Interactive testing education" />
-  <item cmd="2" label="Test Design" description="Create risk-based test plan" />
-  <item cmd="3" label="Test Framework Setup" description="Scaffold test infrastructure" />
-  <item cmd="4" label="CI/CD Setup" description="Quality pipeline configuration" />
-  <item cmd="5" label="ATDD" description="Acceptance test-driven development" />
-  <item cmd="6" label="Test Automation" description="Expand automated test coverage" />
-  <item cmd="7" label="Test Review" description="Review test quality and flakiness" />
-  <item cmd="8" label="NFR Assessment" description="Non-functional requirements assessment" />
-  <item cmd="9" label="Traceability" description="Requirements-to-tests traceability" />
-</menu>
-
-<greeting>
-Sable here. Test architect.
-
-I see testing through a risk lens — not everything needs the same depth of coverage. Let's figure out where the real risks are and build quality gates that actually work.
-
-1. **Teach Me Testing** — learn testing progressively
-2. **Test Design** — risk-based test plan for your system
-3. **Test Framework Setup** — scaffold your test infrastructure
-4. **CI/CD Setup** — quality pipeline with automated gates
-5. **ATDD** — acceptance test-driven development
-6. **Test Automation** — expand your automated coverage
-7. **Test Review** — audit existing test quality
-8. **NFR Assessment** — performance, security, reliability
-9. **Traceability** — requirements-to-tests matrix
-
-What's the risk profile we're working with?
-</greeting>
-
-</agent>
-```

package/_gaia/testing/config.yaml

@@ -1,8 +0,0 @@
-# Testing module config — inherits global
-inherits: "{project-root}/_gaia/_config/global.yaml"
-
-module_name: "testing"
-module_version: "1.8.0"
-
-test_artifacts: "{project-root}/docs/test-artifacts"
-knowledge_path: "{project-root}/_gaia/testing/knowledge"

package/_gaia/testing/knowledge/_index.csv

@@ -1,22 +0,0 @@
-tier,fragment,file,description,used_by_workflows
-"core","fixture-architecture","core/fixture-architecture.md","Fixture patterns, factories, pure function wrappers","test-framework,test-automation"
-"core","test-pyramid","core/test-pyramid.md","Test levels and when to use each","test-design,teach-me-testing"
-"core","test-isolation","core/test-isolation.md","Test doubles, dependency injection, database isolation","test-framework,test-review"
-"core","deterministic-testing","core/deterministic-testing.md","Avoiding flaky tests, time control, network determinism","test-review,test-automation"
-"extended","api-testing-patterns","extended/api-testing-patterns.md","Schema validation, contract testing, REST patterns","test-design,test-automation,atdd"
-"extended","risk-governance","extended/risk-governance.md","Risk-based testing, probability-impact matrix","test-design,nfr-assessment"
-"extended","data-factories","extended/data-factories.md","Builder pattern, factory functions, test data","test-framework,test-automation"
-"extended","selector-resilience","extended/selector-resilience.md","data-testid, role-based selectors, resilience","test-automation,test-review"
-"specialized","contract-testing","specialized/contract-testing.md","Consumer-driven contracts with Pact","test-design,ci-setup"
-"specialized","visual-testing","specialized/visual-testing.md","Screenshot comparison, visual regression","test-automation,test-review"
-"specialized","test-healing","specialized/test-healing.md","Self-healing tests, selector fallbacks","test-review"
-"unit-testing","pytest-patterns","unit-testing/pytest-patterns.md","Pytest fixtures, parameterization, mocking, async testing","test-framework,test-automation"
-"unit-testing","jest-vitest-patterns","unit-testing/jest-vitest-patterns.md","Jest/Vitest patterns, RTL, mocking, snapshots","test-framework,test-automation"
-"unit-testing","junit5-patterns","unit-testing/junit5-patterns.md","JUnit 5 patterns, Mockito, Testcontainers, Spring slices","test-framework,test-automation"
-"mobile-testing","appium-patterns","mobile-testing/appium-patterns.md","Appium cross-platform automation, Page Object Model, device farms","mobile-testing,test-automation"
-"mobile-testing","react-native-testing","mobile-testing/react-native-testing.md","Jest + RNTL, Detox E2E, native module mocking","mobile-testing,test-framework"
-"mobile-testing","responsive-testing","mobile-testing/responsive-testing.md","Viewport testing, CSS breakpoints, visual regression, touch vs click","mobile-testing,test-automation"
-"accessibility","axe-core-patterns","accessibility/axe-core-patterns.md","axe-core integration with Playwright/Cypress, CI automation","accessibility-testing,ci-setup"
-"accessibility","wcag-checks","accessibility/wcag-checks.md","WCAG 2.1 Level AA checklist, POUR principles, screen reader testing","accessibility-testing,test-review"
-"performance","k6-patterns","performance/k6-patterns.md","k6 load testing, scenarios, thresholds, CI integration","performance-testing,ci-setup"
-"performance","lighthouse-ci","performance/lighthouse-ci.md","Lighthouse CI, Core Web Vitals, performance budgets, bundle analysis","performance-testing,ci-setup"

package/_gaia/testing/knowledge/accessibility/axe-core-patterns.md

@@ -1,177 +0,0 @@
----
-name: axe-core-patterns
-tier: accessibility
-version: '1.0'
----
-
-# axe-core Patterns
-
-## Principle
-
-axe-core is the de facto standard for automated accessibility testing. It catches
-approximately 30-40% of WCAG violations automatically — the remainder require manual
-testing. Integrate axe-core into your test suite and CI pipeline to prevent regressions
-while complementing with manual audits.
-
-## Rationale
-
-Manual accessibility testing is essential but slow and inconsistent. axe-core provides
-fast, repeatable checks for common violations (missing alt text, insufficient contrast,
-missing labels). Running axe-core in CI prevents new violations from being introduced,
-creating a ratchet effect that improves accessibility over time.
-
-## Pattern Examples
-
-### Playwright Integration
-
-```typescript
-import { test, expect } from '@playwright/test';
-import AxeBuilder from '@axe-core/playwright';
-
-test.describe('Accessibility', () => {
-  test('homepage has no violations', async ({ page }) => {
-    await page.goto('/');
-
-    const results = await new AxeBuilder({ page })
-      .withTags(['wcag2a', 'wcag2aa', 'wcag21aa'])
-      .analyze();
-
-    expect(results.violations).toEqual([]);
-  });
-
-  test('login form is accessible', async ({ page }) => {
-    await page.goto('/login');
-
-    const results = await new AxeBuilder({ page })
-      .include('[data-testid="login-form"]')
-      .analyze();
-
-    expect(results.violations).toEqual([]);
-  });
-});
-```
-
-### Cypress Integration
-
-```javascript
-// cypress/support/commands.js
-import 'cypress-axe';
-
-// cypress/e2e/accessibility.cy.js
-describe('Accessibility', () => {
-  beforeEach(() => {
-    cy.visit('/');
-    cy.injectAxe();
-  });
-
-  it('has no violations on homepage', () => {
-    cy.checkA11y(null, {
-      runOnly: {
-        type: 'tag',
-        values: ['wcag2a', 'wcag2aa'],
-      },
-    });
-  });
-
-  it('has no violations on modal', () => {
-    cy.get('[data-testid="open-modal"]').click();
-    cy.checkA11y('[data-testid="modal"]');
-  });
-});
-```
-
-### Rule Configuration
-
-```typescript
-// Disable specific rules when you have a known exception
-const results = await new AxeBuilder({ page })
-  .disableRules(['color-contrast']) // only if you have a documented exception
-  .analyze();
-
-// Run only specific rules
-const results = await new AxeBuilder({ page })
-  .withRules(['label', 'image-alt', 'button-name', 'link-name'])
-  .analyze();
-
-// Target specific WCAG levels
-const results = await new AxeBuilder({ page })
-  .withTags(['wcag2a'])       // Level A only
-  .withTags(['wcag2aa'])      // Level AA
-  .withTags(['wcag21aa'])     // WCAG 2.1 Level AA
-  .analyze();
-```
-
-### CI Integration
-
-```yaml
-# GitHub Actions
-- name: Run accessibility tests
-  run: npx playwright test tests/accessibility/
-  env:
-    CI: true
-
-# Custom reporter for CI visibility
-- name: Upload axe results
-  if: always()
-  uses: actions/upload-artifact@v4
-  with:
-    name: accessibility-report
-    path: test-results/accessibility/
-```
-
-### Custom Result Handling
-
-```typescript
-function formatViolations(violations: axe.Result[]): string {
-  return violations
-    .map((v) => {
-      const nodes = v.nodes.map((n) => `  - ${n.html} (${n.failureSummary})`).join('\n');
-      return `${v.id} (${v.impact}): ${v.description}\n${nodes}`;
-    })
-    .join('\n\n');
-}
-
-test('check and report violations', async ({ page }) => {
-  await page.goto('/dashboard');
-  const results = await new AxeBuilder({ page }).analyze();
-
-  if (results.violations.length > 0) {
-    console.log('Accessibility violations found:\n' + formatViolations(results.violations));
-  }
-  expect(results.violations).toEqual([]);
-});
-```
-
-### Common Violations and Fixes
-
-| Violation | Impact | Fix |
-|-----------|--------|-----|
-| `image-alt` | Critical | Add `alt` attribute to all `<img>` tags |
-| `button-name` | Critical | Add text content or `aria-label` to buttons |
-| `link-name` | Serious | Add descriptive text to all links |
-| `color-contrast` | Serious | Ensure 4.5:1 ratio for normal text, 3:1 for large |
-| `label` | Critical | Associate `<label>` with form inputs via `for`/`id` |
-| `region` | Moderate | Wrap content in landmark regions |
-
-## Anti-Patterns
-
-1. **Disabling rules without justification** — Every disabled rule should have a
-   documented exception with a plan to fix.
-
-2. **Running axe-core only in development** — Accessibility checks belong in CI.
-   New code should never introduce violations.
-
-3. **Testing only the homepage** — Run axe-core on every page and every state
-   (modals open, forms with errors, loading states).
-
-4. **Treating axe-core as complete** — axe-core catches 30-40% of issues. Manual
-   testing for keyboard nav, screen readers, and focus management is still required.
-
-5. **Ignoring incomplete results** — axe-core reports "incomplete" for checks that
-   need human review. These are not passes — review them.
-
-## Integration Points
-
-- **Tools**: axe-core, @axe-core/playwright, cypress-axe, pa11y
-- **Workflows**: `accessibility-testing` (test plan), `ci-setup` (pipeline integration)
-- **Related fragments**: `wcag-checks` (manual testing checklist)

package/_gaia/testing/knowledge/accessibility/wcag-checks.md

@@ -1,191 +0,0 @@
----
-name: wcag-checks
-tier: accessibility
-version: '1.0'
----
-
-# WCAG 2.1 Checks
-
-## Principle
-
-WCAG 2.1 Level AA is the baseline standard for web accessibility. The four principles
-— Perceivable, Operable, Understandable, Robust (POUR) — provide a framework for
-evaluating accessibility. Each principle contains guidelines with specific, testable
-success criteria.
-
-## Rationale
-
-Legal requirements (ADA, EAA, Section 508) increasingly mandate WCAG 2.1 AA compliance.
-Beyond compliance, accessible design improves usability for all users — keyboard
-navigation helps power users, captions help users in noisy environments, and clear
-structure helps everyone. Testing against POUR ensures comprehensive coverage.
-
-## Pattern Examples
-
-### Perceivable
-
-**1.1 Text Alternatives**
-```html
-<!-- Good: Informative alt text -->
-<img src="chart.png" alt="Q3 revenue increased 15% to $2.3M" />
-
-<!-- Good: Decorative image -->
-<img src="divider.png" alt="" role="presentation" />
-
-<!-- Bad: Missing or meaningless alt -->
-<img src="chart.png" />
-<img src="chart.png" alt="image" />
-```
-
-**1.3 Adaptable — Correct heading hierarchy**
-```html
-<!-- Good: Logical hierarchy -->
-<h1>Dashboard</h1>
-  <h2>Sales Overview</h2>
-    <h3>Monthly Trends</h3>
-  <h2>Customer Metrics</h2>
-
-<!-- Bad: Skipped levels -->
-<h1>Dashboard</h1>
-  <h3>Sales Overview</h3>  <!-- skipped h2 -->
-```
-
-**1.4 Distinguishable — Color contrast**
-```css
-/* Good: 4.5:1 ratio for normal text */
-.body-text { color: #333333; background: #ffffff; } /* 12.6:1 */
-
-/* Good: 3:1 ratio for large text (18px+ or 14px+ bold) */
-.heading { color: #767676; background: #ffffff; font-size: 24px; } /* 4.5:1 */
-
-/* Bad: Insufficient contrast */
-.light-text { color: #aaaaaa; background: #ffffff; } /* 2.3:1 */
-```
-
-### Operable
-
-**2.1 Keyboard Accessible**
-```typescript
-// Test: All interactive elements reachable by Tab
-test('keyboard navigation covers all actions', async ({ page }) => {
-  await page.goto('/form');
-  const tabbableElements = await page.evaluate(() => {
-    const elements: string[] = [];
-    let el = document.body;
-    while (el = document.activeElement as HTMLElement) {
-      elements.push(el.tagName + (el.id ? '#' + el.id : ''));
-      (el as HTMLElement).dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab' }));
-      if (elements.length > 50) break;
-    }
-    return elements;
-  });
-  expect(tabbableElements).toContain('BUTTON#submit');
-});
-
-// Test: No keyboard trap
-test('escape closes modal', async ({ page }) => {
-  await page.click('[data-testid="open-modal"]');
-  await page.keyboard.press('Escape');
-  await expect(page.locator('[data-testid="modal"]')).toBeHidden();
-});
-```
-
-**2.4 Navigable — Focus indicators**
-```css
-/* Good: Visible focus indicator */
-:focus-visible {
-  outline: 2px solid #0066cc;
-  outline-offset: 2px;
-}
-
-/* Bad: Removing focus indicator */
-:focus { outline: none; } /* NEVER do this without a replacement */
-```
-
-### Understandable
-
-**3.1 Readable — Language declared**
-```html
-<html lang="en">
-<!-- For multilingual content -->
-<p>The French word <span lang="fr">bonjour</span> means hello.</p>
-```
-
-**3.2 Predictable — Consistent navigation**
-```html
-<!-- Navigation must be consistent across pages -->
-<nav aria-label="Main navigation">
-  <ul>
-    <li><a href="/" aria-current="page">Home</a></li>
-    <li><a href="/about">About</a></li>
-    <li><a href="/contact">Contact</a></li>
-  </ul>
-</nav>
-```
-
-**3.3 Input Assistance — Error handling**
-```html
-<!-- Good: Error identified and described -->
-<label for="email">Email</label>
-<input id="email" type="email" aria-describedby="email-error" aria-invalid="true" />
-<p id="email-error" role="alert">Please enter a valid email address (e.g., user@example.com)</p>
-```
-
-### Robust
-
-**4.1 Compatible — Valid ARIA**
-```html
-<!-- Good: Correct ARIA usage -->
-<button aria-expanded="false" aria-controls="menu-dropdown">Menu</button>
-<ul id="menu-dropdown" role="menu" hidden>
-  <li role="menuitem"><a href="/profile">Profile</a></li>
-</ul>
-
-<!-- Bad: Conflicting roles -->
-<div role="button" role="link">Click me</div>
-```
-
-### Testing Tools Quick Reference
-
-| Tool | Purpose | Automated? |
-|------|---------|-----------|
-| axe-core | Rule-based WCAG scanning | Yes |
-| Lighthouse | Accessibility score + audit | Yes |
-| WAVE | Visual overlay of issues | Semi |
-| VoiceOver (macOS/iOS) | Screen reader testing | Manual |
-| NVDA (Windows) | Screen reader testing | Manual |
-| Colour Contrast Analyser | Contrast ratio checking | Manual |
-| Keyboard only | Tab/Enter/Space navigation | Manual |
-
-### Screen Reader Testing Procedure
-
-1. Turn on screen reader (VoiceOver: Cmd+F5, NVDA: Ctrl+Alt+N)
-2. Navigate page with Tab key — verify all interactive elements announced
-3. Read through headings (VO: Ctrl+Alt+Cmd+H) — verify logical order
-4. Complete primary user flow using only keyboard
-5. Verify form labels read correctly when fields focused
-6. Check dynamic content updates announced via live regions
-7. Verify modal focus trap works correctly
-
-## Anti-Patterns
-
-1. **ARIA overuse** — Adding ARIA to elements that already have semantic meaning.
-   `<button>` does not need `role="button"`. Use semantic HTML first.
-
-2. **Color as sole indicator** — Using only color to convey information (red for error,
-   green for success). Add icons, text, or patterns alongside color.
-
-3. **Removing focus indicators** — `outline: none` without a visible replacement makes
-   keyboard navigation impossible.
-
-4. **Auto-playing media** — Audio or video that plays automatically without user control
-   violates WCAG 1.4.2.
-
-5. **Non-descriptive links** — "Click here" and "Read more" links provide no context
-   to screen reader users. Use descriptive link text.
-
-## Integration Points
-
-- **Tools**: axe-core, VoiceOver, NVDA, Lighthouse, WAVE
-- **Workflows**: `accessibility-testing` (test plan), `test-review` (quality checks)
-- **Related fragments**: `axe-core-patterns` (automated testing)