@keber/qa-framework 1.10.0 → 1.12.0

package/templates/integration-scaffold/.env.example

@@ -0,0 +1,40 @@
+# -----------------------------------------------------------------------
+# Integration test environment variables
+# -----------------------------------------------------------------------
+# Copy this file to .env and fill in real values.
+# NEVER commit .env to source control.
+# -----------------------------------------------------------------------
+
+# -----------------------------------------------------------------------
+# Application under test
+# -----------------------------------------------------------------------
+QA_BASE_URL=https://your-app.qa.example.com
+
+# -----------------------------------------------------------------------
+# Auth - choose one strategy
+# -----------------------------------------------------------------------
+
+# Strategy 1: Static bearer token (preferred for pure API services)
+# QA_API_TOKEN=your-api-token-here
+
+# Strategy 2: Browser login (for apps with cookie/session auth)
+# QA_USER_EMAIL=qa-user@example.com
+# QA_USER_PASSWORD=CHANGE_ME
+
+# -----------------------------------------------------------------------
+# Login form selectors (used only when QA_API_TOKEN is not set)
+# -----------------------------------------------------------------------
+# QA_LOGIN_PATH=/login
+# QA_LOGIN_EMAIL_SELECTOR=input[type="email"]
+# QA_LOGIN_PASSWORD_SELECTOR=input[type="password"]
+# QA_LOGIN_SUBMIT_SELECTOR=button[type="submit"]
+# QA_LOGIN_SUCCESS_SELECTOR=.dashboard
+
+# -----------------------------------------------------------------------
+# Azure DevOps integration (optional)
+# -----------------------------------------------------------------------
+# ADO_ORG=your-org
+# ADO_PROJECT=YourProject
+# ADO_PLAN_ID=00000
+# ADO_PAT=your-pat-here
+# SYSTEM_ACCESSTOKEN=   # Set automatically in Azure Pipelines

package/templates/integration-scaffold/README.md

@@ -0,0 +1,77 @@
+# API Integration Tests
+
+Playwright-based API test project for `qa/07-automation/integration/`.
+
+Tests run without a browser. All tests use Playwright's `APIRequestContext`
+to call HTTP endpoints directly. Auth state is established once by
+`global-setup.ts` and reused across the test run.
+
+## Requirements
+
+- Node.js 18+
+- `@playwright/test` (installed via `npm install` in this directory)
+
+## Setup
+
+```bash
+cd qa/07-automation/integration
+npm install
+cp .env.example .env
+# Edit .env and fill in QA_BASE_URL and auth credentials
+```
+
+Add the following to your root `.gitignore`:
+
+```
+qa/07-automation/integration/.env
+qa/07-automation/integration/.auth/
+qa/07-automation/integration/test-results/
+qa/07-automation/integration/playwright-report/
+```
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `QA_BASE_URL` | Yes | Base URL of the API under test |
+| `QA_API_TOKEN` | One of | Static bearer token for token-based APIs |
+| `QA_USER_EMAIL` | One of | Email/username for browser-login APIs |
+| `QA_USER_PASSWORD` | One of | Password for browser-login APIs |
+
+See `.env.example` for all supported variables.
+
+## Running tests
+
+```bash
+# All tests
+npm test
+
+# CI mode (retries enabled)
+npm run test:ci
+
+# Open HTML report
+npm run report
+```
+
+## Writing tests
+
+Import from `@playwright/test` and use the `request` fixture:
+
+```typescript
+import { test, expect } from '@playwright/test';
+
+test('GET /users returns 200', async ({ request }) => {
+  const response = await request.get('/users');
+  expect(response.status()).toBe(200);
+});
+```
+
+For token-based APIs that require an `Authorization` header, pass it per request:
+
+```typescript
+const response = await request.get('/api/protected', {
+  headers: { Authorization: `Bearer ${process.env.QA_API_TOKEN}` },
+});
+```
+
+See `tests/example.spec.ts` for a starter test to replace.

package/templates/integration-scaffold/global-setup.ts

@@ -0,0 +1,119 @@
+/**
+ * global-setup.ts - Integration (API-only) project
+ *
+ * Runs once before all test files to establish auth state.
+ *
+ * Two strategies, tried in order:
+ *   1. Token-based: QA_API_TOKEN is set -> write a minimal storageState with the
+ *      token in localStorage so the `request` fixture picks it up automatically.
+ *   2. Browser login: QA_USER_EMAIL + QA_USER_PASSWORD are set -> launch Chromium,
+ *      perform the login flow, and save the resulting storageState to
+ *      .auth/api-session.json.
+ *
+ * Playwright's `storageState` mechanism handles cookies and localStorage for
+ * APIRequestContext automatically when `use.storageState` is configured.
+ * For token-only APIs that require an Authorization header, set the header
+ * directly in each test or extend the `request` fixture in fixtures/base.ts.
+ */
+
+import * as fs   from 'fs';
+import * as path from 'path';
+import { chromium } from '@playwright/test';
+import * as dotenv  from 'dotenv';
+
+dotenv.config();
+
+const AUTH_FILE = path.join(__dirname, '.auth', 'api-session.json');
+
+export default async function globalSetup(): Promise<void> {
+  fs.mkdirSync(path.dirname(AUTH_FILE), { recursive: true });
+
+  if (process.env.QA_API_TOKEN) {
+    await setupWithToken(process.env.QA_API_TOKEN, process.env.QA_BASE_URL!);
+    return;
+  }
+
+  await setupWithBrowserLogin();
+}
+
+/**
+ * Write a minimal storageState that carries the bearer token in localStorage.
+ * Replace the localStorage key/value format if your app uses a different scheme
+ * (e.g. a cookie, or a different localStorage key name).
+ */
+async function setupWithToken(token: string, baseURL: string): Promise<void> {
+  const origin = baseURL.replace(/\/$/, '');
+
+  const state = {
+    cookies: [],
+    origins: [
+      {
+        origin,
+        localStorage: [
+          { name: 'qa_api_token', value: token },
+        ],
+      },
+    ],
+  };
+
+  fs.writeFileSync(AUTH_FILE, JSON.stringify(state, null, 2), 'utf-8');
+  console.log('[integration-setup] Token-based auth written to api-session.json');
+}
+
+/**
+ * Perform a browser login and save the resulting cookies + localStorage to disk.
+ *
+ * Configure login form selectors via env vars (see .env.example) or update the
+ * defaults below to match your application's login page.
+ */
+async function setupWithBrowserLogin(): Promise<void> {
+  const baseURL          = process.env.QA_BASE_URL!.replace(/\/$/, '');
+  const email            = process.env.QA_USER_EMAIL!;
+  const password         = process.env.QA_USER_PASSWORD!;
+  const loginPath        = process.env.QA_LOGIN_PATH              ?? '/login';
+  const emailSelector    = process.env.QA_LOGIN_EMAIL_SELECTOR    ?? 'input[type="email"]';
+  const passwordSelector = process.env.QA_LOGIN_PASSWORD_SELECTOR ?? 'input[type="password"]';
+  const submitSelector   = process.env.QA_LOGIN_SUBMIT_SELECTOR   ?? 'button[type="submit"]';
+  const successSelector  = process.env.QA_LOGIN_SUCCESS_SELECTOR  ?? '.dashboard, .main-content, [data-testid="app-shell"]';
+
+  console.log('[integration-setup] Performing browser login...');
+
+  const browser = await chromium.launch();
+  const context = await browser.newContext();
+  const page    = await context.newPage();
+
+  try {
+    await page.goto(`${baseURL}${loginPath}`, { waitUntil: 'load', timeout: 60_000 });
+
+    await page.locator(emailSelector).waitFor({ state: 'visible', timeout: 30_000 });
+    await page.locator(emailSelector).fill(email);
+    // Trace safety: Playwright records fill() argument values in traces, so a project
+    // that enables trace/video capture would persist the plaintext password in its
+    // artifacts. Setting the value through evaluate() keeps it out of the trace.
+    // Do not "simplify" this back to fill().
+    // The input/change events are required because assigning .value directly does
+    // not notify SPA frameworks (Blazor/Radzen bind on those events).
+    // evaluate() has no auto-wait, so the explicit waitFor replaces the one that
+    // locator().fill() performed implicitly.
+    await page.locator(passwordSelector).waitFor({ state: 'visible', timeout: 30_000 });
+    await page.evaluate(
+      ([selector, pwd]) => {
+        const input = document.querySelector(selector) as HTMLInputElement | null;
+        if (!input) {
+          throw new Error(`[qa-framework] Password input not found for selector: ${selector}`);
+        }
+        input.value = pwd;
+        input.dispatchEvent(new Event('input', { bubbles: true }));
+        input.dispatchEvent(new Event('change', { bubbles: true }));
+      },
+      [passwordSelector, password] as const
+    );
+    await page.locator(submitSelector).click();
+    await page.waitForSelector(successSelector, { timeout: 60_000 });
+
+    await context.storageState({ path: AUTH_FILE });
+    console.log(`[integration-setup] Auth saved: ${AUTH_FILE}`);
+  } finally {
+    await browser.close();
+  }
+}

package/templates/integration-scaffold/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "qa-integration-tests",
+  "version": "1.0.0",
+  "description": "API integration tests - no browser required",
+  "private": true,
+  "scripts": {
+    "test":    "playwright test",
+    "test:ci": "CI=true playwright test",
+    "report":  "playwright show-report"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.44.0",
+    "dotenv":           "^16.4.0"
+  }
+}

package/templates/integration-scaffold/playwright.config.ts

@@ -0,0 +1,92 @@
+/**
+ * playwright.config.ts - API integration test project (no browser)
+ *
+ * All tests use APIRequestContext directly. No browser projects are defined.
+ * Auth is handled by global-setup.ts, which writes .auth/api-session.json.
+ *
+ * Required env vars:
+ *   QA_BASE_URL     - Base URL of the API under test
+ *
+ * Auth (at least one of the following):
+ *   QA_API_TOKEN    - Bearer token (skips browser login in global-setup)
+ *   QA_USER_EMAIL + QA_USER_PASSWORD  - Credentials for browser-based login
+ */
+
+import { defineConfig } from '@playwright/test';
+import * as dotenv from 'dotenv';
+import * as fs from 'fs';
+
+// Least privilege: read only the keys this config actually uses. dotenv.parse() returns
+// a plain object without touching process.env, so the other secrets in .env - the other
+// QA accounts, ADO tokens - are never loaded into a process that has no use for them.
+// QA_USER_PASSWORD is included because the credentials check below reads it; its value
+// is only tested for presence, never logged. Do not "simplify" this back to config().
+const ENV_KEYS = ['QA_BASE_URL', 'QA_API_TOKEN', 'QA_USER_EMAIL', 'QA_USER_PASSWORD'] as const;
+if (fs.existsSync('.env')) {
+  const parsed = dotenv.parse(fs.readFileSync('.env'));
+  for (const key of ENV_KEYS) {
+    if (process.env[key] === undefined && parsed[key] !== undefined) {
+      process.env[key] = parsed[key];
+    }
+  }
+}
+
+const required = ['QA_BASE_URL'];
+for (const key of required) {
+  if (!process.env[key]) {
+    throw new Error(`[integration] Missing required env var: ${key}. Check your .env file.`);
+  }
+}
+
+const hasToken = !!process.env.QA_API_TOKEN;
+const hasCredentials = !!(process.env.QA_USER_EMAIL && process.env.QA_USER_PASSWORD);
+
+if (!hasToken && !hasCredentials) {
+  throw new Error(
+    '[integration] No auth configured. Set QA_API_TOKEN, or both QA_USER_EMAIL and QA_USER_PASSWORD.',
+  );
+}
+
+// Optional: Azure DevOps reporter configuration
+// To enable: set env vars ADO_ORG, ADO_PROJECT, ADO_PAT, ADO_PLAN_ID and CI=true,
+// then uncomment the reporter entry in the `reporter` array below.
+// Install:  npm install @alex_neo/playwright-azure-reporter --save-dev
+// const adoReporterConfig = {
+//   orgUrl:                  `https://dev.azure.com/${process.env.ADO_ORG}`,
+//   token:                   process.env.SYSTEM_ACCESSTOKEN ?? process.env.ADO_PAT,
+//   planId:                  Number(process.env.ADO_PLAN_ID),
+//   projectName:             process.env.ADO_PROJECT!,
+//   testRunTitle:            `[Auto API] ${new Date().toISOString().slice(0, 10)}`,
+//   publishTestResultsMode:  'testRun' as const,
+//   uploadAttachments:       false,
+//   isDisabled:              !process.env.CI,
+//   autoMarkTestCasesAsAutomated: {
+//     enabled:                    true,
+//     updateAutomatedTestName:    true,
+//     updateAutomatedTestStorage: true,
+//   },
+// };
+
+export default defineConfig({
+  testDir:       './tests',
+  fullyParallel: false,
+  workers:       1,
+  timeout:       30_000,
+  retries:       process.env.CI ? 1 : 0,
+
+  globalSetup:  './global-setup.ts',
+
+  reporter: [
+    ['list'],
+    ['html', { open: 'never', outputFolder: 'playwright-report' }],
+    // Uncomment for ADO:
+    // ['@alex_neo/playwright-azure-reporter', adoReporterConfig],
+  ],
+
+  use: {
+    baseURL:      process.env.QA_BASE_URL,
+    storageState: '.auth/api-session.json',
+  },
+
+  outputDir: 'test-results/',
+});

package/templates/integration-scaffold/tests/example.spec.ts

@@ -0,0 +1,43 @@
+/**
+ * example.spec.ts - API integration test example
+ *
+ * This file shows the basic pattern for API tests using Playwright's
+ * APIRequestContext. Replace this with your real tests.
+ *
+ * The `request` fixture is pre-configured with:
+ *   - baseURL from QA_BASE_URL
+ *   - storageState from .auth/api-session.json (set by global-setup.ts)
+ *
+ * For token-based APIs that require an Authorization header, add it
+ * explicitly per request or extend the fixture in a fixtures/base.ts file.
+ */
+
+import { test, expect } from '@playwright/test';
+
+// Replace with the actual health/status endpoint of your API.
+const HEALTH_ENDPOINT = '/health';
+
+test.describe('API smoke tests', () => {
+
+  test('GET health endpoint returns 200', async ({ request }) => {
+    const response = await request.get(HEALTH_ENDPOINT);
+
+    expect(response.status()).toBe(200);
+  });
+
+  // Example of a test with an Authorization header when QA_API_TOKEN is set.
+  // Uncomment and adapt when your API uses Bearer token auth.
+  //
+  // test('GET protected resource returns 200 with bearer token', async ({ request }) => {
+  //   const response = await request.get('/api/me', {
+  //     headers: {
+  //       Authorization: `Bearer ${process.env.QA_API_TOKEN}`,
+  //     },
+  //   });
+  //
+  //   expect(response.status()).toBe(200);
+  //   const body = await response.json();
+  //   expect(body).toHaveProperty('id');
+  // });
+
+});

package/templates/memory/ci-pipeline-findings.md

@@ -0,0 +1,36 @@
+# CI Pipeline Findings
+
+> Document CI pipeline issues, root causes, and applied fixes as they are discovered.
+> This file is loaded by the agent when diagnosing CI failures or reviewing pipeline changes.
+
+## Applied Fixes
+
+Document each fix that was applied to the pipeline or test setup. Use a table or prose - whatever fits the change.
+
+| Problem | Root cause | Fix applied |
+|---|---|---|
+| _Add pipeline issue here_ | _Root cause_ | _What was changed and where_ |
+
+> Examples: auth setup defaults, missing reporter packages, artifact name collisions,
+> browser binary not installed in a CI stage, grep flag escaping issues.
+
+## Known Limitations
+
+Document constraints that are accepted but not fixed (timeout budgets, worker counts, retry behavior).
+
+> Examples:
+> - Full suite exceeds the CI timeout with 1 worker. Workaround: run only P0/P1 tags by default.
+> - `retries: 2` counts each attempt separately, so reported execution count exceeds test count.
+> - Attachment upload warnings on `PublishTestResults` when multiple failures share filenames.
+
+## Failure Triage Categories
+
+Use these categories when classifying CI failures. Add project-specific categories as needed.
+
+| Category | Description | Action |
+|---|---|---|
+| TIMEOUT | Test exceeded its time budget | Adjust `timeout` in the spec or in `playwright.config.ts` |
+| SESSION | Auth session expired mid-run | Implement session-refresh fixture or reduce suite duration |
+| FLAKY | Intermittent failure, passes on retry | Acceptable if retries cover it; investigate if failure rate > 20% |
+| APP-DEFECT | Application does not meet the spec | Open defect file; mark test with `test.fail()` |
+| TEST-CODE | Selector or assertion is wrong in CI | Fix the spec file |

package/templates/memory/data-volatility-strategies.md

@@ -0,0 +1,70 @@
+# Data Volatility Strategies
+
+> The QA environment is typically shared between automated tests and manual testers.
+> Data (record counts, available filter values, document states) changes constantly,
+> which invalidates hardcoded values in specs. Document the chosen strategy here.
+
+## Problem
+
+List the types of data that are volatile in this project's QA environment.
+
+| Data type | Example of fragile assertion | Tests affected |
+|---|---|---|
+| Filter option values | `hasText: 'specific-value'` | _Add count here_ |
+| Exact row counts | `toBe(33)` | _Add count here_ |
+| Record names used as search inputs | `fill('specific-record-name')` | _Add count here_ |
+| Process or transaction IDs | `TEST_ID = '608'` | _Add count here_ |
+
+## Strategy 1: Shared Constants with Dynamic Discovery
+
+Maintain a `fixtures/test-data-constants.ts` file with well-named constants. Populate them
+from a discovery step (global-setup or a `beforeAll` fixture) that reads the actual environment.
+
+```typescript
+// fixtures/test-data-constants.ts
+export const QA_ITEM_CURRENT = 'current-item-name';  // most recent available
+export const QA_ITEM_OLDEST  = 'oldest-item-name';   // oldest available
+export const QA_ITEM_INVALID = 'nonexistent-item';   // guaranteed absent
+```
+
+**Tradeoff:** eliminates hardcoded filter values centrally, but discovery adds startup time
+and blocks the suite if it fails.
+
+## Strategy 2: Resilient Assertions (Patterns and Ranges)
+
+Replace exact-value assertions with pattern or range checks.
+
+```typescript
+// Instead of:
+expect(count).toBe(33);
+await expect(counter).toHaveText('1-5 of 5');
+
+// Use:
+expect(count).toBeGreaterThan(0);
+await expect(counter).toHaveText(/\d+-\d+ of \d+/);
+```
+
+**Tradeoff:** no extra infrastructure, each test is self-contained, but precision is lower.
+Useful for count assertions; less useful for filter-value selection.
+
+## Strategy 3: Snapshot Delta Validation
+
+Capture the initial state before applying a filter, then assert that the filtered state
+differs from the initial state in the expected direction (fewer rows, etc.).
+
+**Tradeoff:** maximum resilience, but tests become longer and harder to trace. Use only for
+critical filter tests where behavior (not data) must be validated.
+
+## Chosen Approach
+
+> Document which strategy (or combination) was chosen for this project, and which test
+> categories each strategy applies to.
+
+| Test category | Strategy | Status |
+|---|---|---|
+| Filter option values | Strategy 1 or 2 | _Pending / Implemented_ |
+| Row count assertions | Strategy 2 | _Pending / Implemented_ |
+| Search input values | Strategy 2 or 3 | _Pending / Implemented_ |
+
+> Tests that are blocked on a data strategy can be marked `test.skip()` with a
+> `PENDING-DATA-STRATEGY` annotation until the strategy is implemented.

package/templates/memory/e2e-stabilization-patterns.md

@@ -0,0 +1,54 @@
+# E2E Stabilization Patterns
+
+> A running log of flakiness patterns found in this project and the techniques used to fix them.
+> Load this file when investigating intermittent test failures or refactoring fragile specs.
+
+## Crash-Recovery Pattern
+
+When the application server crashes intermittently (e.g. unhandled error page with a Reload link),
+a bare `waitFor` will timeout. Use `Promise.race` to detect the error state and recover:
+
+```typescript
+const outcome = await Promise.race([
+  targetElement.waitFor({ state: 'visible', timeout: 60_000 }).then(() => 'ready' as const),
+  page.getByText('An unhandled error has occurred.').waitFor({ state: 'visible', timeout: 60_000 }).then(() => 'crash' as const),
+]).catch(() => 'timeout' as const);
+
+if (outcome === 'crash') {
+  await page.getByRole('link', { name: 'Reload' }).click();
+  await targetElement.waitFor({ state: 'visible', timeout: 60_000 });
+}
+```
+
+> Document which spec files use this pattern and under what conditions it fires.
+
+## Strict-Mode Selector Conflicts
+
+`getByText()` and similar matchers can match multiple elements, triggering strict-mode violations.
+Scope selectors to the most specific container available.
+
+> Document conflicts found in this project here.
+> Example: a pagination counter regex that also matches a card element.
+> Fix: use a scoped `locator('.specific-class')` instead of a broad text match.
+
+## Known Flaky Failure Types
+
+Document categories of instability specific to this project. A row per pattern is enough.
+
+| ID | Root cause | Fix | Affected tests |
+|---|---|---|---|
+| _Add ID_ | _Describe the underlying cause_ | _Technique used to fix_ | _Spec files or TC IDs_ |
+
+> Examples: framework hydration delays, input binding issues requiring `pressSequentially`,
+> elements that are in the DOM but not yet rendered, session expiry during long runs.
+
+## Reference Timeouts
+
+Fill in the timeout values used in this project once they are stabilized.
+
+| Setting | Value | Location |
+|---|---|---|
+| Default test timeout | - | `playwright.config.ts` |
+| `actionTimeout` | - | `playwright.config.ts` |
+| `navigationTimeout` | - | `playwright.config.ts` |
+| Long-running spec timeout | - | Per-spec `describe.configure` |

package/templates/qa-framework.instructions.md

@@ -8,7 +8,7 @@ This project uses `@keber/qa-framework` v{{VERSION}} for spec-driven automated t
 ## Agent behavior rules
 
 0. **On every conversation start:** check if `qa/AGENT-NEXT-STEPS.md` exists. If it does, read it and complete its steps before anything else.
-1. Before performing any QA task, load the relevant skill from `.github/skills/`. For project context, read `qa/memory/INDEX.md` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
+1. Before performing any QA task, load the relevant skill from `.github/skills/`. For project context, read `qa/memory/INDEX.md` if it exists, then load only the memory files relevant to the current task - do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
 2. Always save artifacts in the correct `qa/` subfolder - refer to `qa/QA-STRUCTURE-GUIDE.md`
 3. Never hardcode credentials - always use env vars and `<PLACEHOLDER>` in documentation
 4. Follow the naming conventions in `qa/00-standards/naming-conventions.md`
@@ -16,15 +16,24 @@ This project uses `@keber/qa-framework` v{{VERSION}} for spec-driven automated t
 6. Project QA config is at `qa/qa-framework.config.json`
 7. Save learnings in `qa/memory/` with proper naming and metadata. Always update `qa/memory/INDEX.md` after adding or updating any memory file.
 8. **Sprint/module completion criteria:** A sprint or module is complete when every TC in scope has one of these three valid states - and no other: (a) `test()` passing: the app meets the spec; (b) `test.fail()`: the app violates the spec **and** a file `qa/06-defects/open/DEF-SIS-NNN_*.md` exists documenting which business rule is violated and what the app actually does; (c) `test.skip()`: the TC is not yet executable, annotated with `PENDING-CODE` and a linked issue. A sprint is **not** complete if any TC is failing without `test.fail()`, or has `test.fail()` without a defect file, or has `test.skip()` without a `PENDING-CODE` reason.
-9. **On sprint/module completion:** (1) update the module status row in `qa/README.md`; (2) move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`; (3) trim `AGENT-NEXT-STEPS.md` so it contains only the next sprint — never let it accumulate more than one active sprint.
-10. **Assertion polarity rule (BLOCKING):** A test must assert what the **spec** requires, not what the app currently does. If the app fails to meet the spec, use `test.fail()` + correct assertion to document the defect — **never invert or weaken an assertion to make a test go green.** A failing test that exposes a real defect is always more valuable than a passing test that hides one.
+9. **On sprint/module completion:** (1) update the module status row in `qa/README.md`; (2) move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`; (3) trim `AGENT-NEXT-STEPS.md` so it contains only the next sprint - never let it accumulate more than one active sprint.
+10. **Assertion polarity rule (BLOCKING):** A test must assert what the **spec** requires, not what the app currently does. If the app fails to meet the spec, use `test.fail()` + correct assertion to document the defect - **never invert or weaken an assertion to make a test go green.** A failing test that exposes a real defect is always more valuable than a passing test that hides one.
 11. **Character encoding safety (BLOCKING):** In ALL generated content (markdown, scripts, test titles, ADO fields, config files), never use characters at these Unicode code points: em-dash (U+2014), en-dash (U+2013), horizontal ellipsis (U+2026), smart/curly quotes (U+201C, U+201D, U+2018, U+2019), or directional arrows (U+2190-U+21FF). Use ASCII equivalents instead: ` - ` (hyphen with surrounding spaces) for dashes, `...` for ellipsis, `"` and `'` for quotes, `->` and `<-` for arrows. Exception: Latin Extended characters (U+00C0-U+024F) are always permitted - this covers Spanish vowels with accents (U+00E0-U+00FA), n with tilde (U+00F1/U+00D1), and u/o with umlaut (U+00FC/U+00DC, U+00F6/U+00D6).
+12. **Lane lock for parallel QA execution (BLOCKING):** Parallel QA lanes exist because the applications under test invalidate a session when the same account logs in again - two concurrent workers on one account silently destroy each other's session, and the damage surfaces later as an unexplained logout or as evidence recorded under the wrong account. Before dispatching any worker (sub-agent, test runner project, or CI job) against one of the lanes configured in `parallelLanes.lanes` in `qa/qa-framework.config.json`, **acquire a lane through the project's lane-lock script and release it when the work is done.** Never assign a lane by prompt or config alone without going through the lock. Use `acquire` when the worker does not care which lane it gets, and `reserve <laneId>` when it needs a specific predictable lane (a CI job or a local CLI run) - these are two verbs because there are two use cases, and collapsing them is how a CI job lands on a random lane. If no lane is free, queue (capped at the configured lane count) or reject - **never force a lane assignment past that cap.** Check that a lane actually has the capability a worker needs before handing it over: capabilities are per-lane, so a lane that lacks (for example) an MCP server must not be given to a worker that needs one. A held lane is swept as stale only after the configured threshold and only when no recent heartbeat proves the holder alive, so **the dispatcher must keep the lane alive with `heartbeat` while the work is in flight** - do not rely on the dispatched worker to do it, since a worker that was never told the mechanism exists cannot be expected to use it. A lock held far longer than the app's session TTL is a signal to verify, not a defect to ignore; each project's agent-specific instructions define how it verifies a lock is still legitimately held and how it clears a stale one.
 
 ## Formatting rules for generated content
 1. Generate the output in `UTF-8` encoding without BOM (`UTF-8`, no signature).
 2. Ensure the raw output is `UTF-8` encoded with no `EF BB BF` bytes at the beginning.
 
-{{ADO_SECTION}}
+## Azure DevOps integration
+
+Before any ADO operation, check if `.github/skills/ado-qa/` exists or if
+`integrations.azureDevOps.enabled` is `true` in `qa/qa-framework.config.json`. If either
+condition is met, load `.github/skills/qa-ado-integration/SKILL.md` and use it for
+all ADO interactions (work items, test plans, test cases, bugs, etc.).
+
+> To enable Azure DevOps integration run: `npm install github:keber/ado-qa`
+
 ## QA Pipeline
 
 Stages must run in order. Never start a stage unless its prerequisite is met.
@@ -38,8 +47,8 @@ Stages must run in order. Never start a stage unless its prerequisite is met.
 | 5 | Generate automation | `.github/skills/qa-automation/SKILL.md` | Specs approved, no PENDING-CODE |
 | 5b | Stabilize failing tests | `.github/skills/qa-test-stabilization/SKILL.md` | Failing tests exist |
 | 6 | Maintenance | `.github/skills/qa-maintenance/SKILL.md` | Application change delivered |
-| — | ADO integration | `.github/skills/qa-ado-integration/SKILL.md` | ADO enabled in config |
+| - | ADO integration | `.github/skills/qa-ado-integration/SKILL.md` | ADO enabled in config |
 
 ## Project KB
-1. `qa/README.md`          — The Living Index: module status, sprint history, blockers, quick-start commands.
-2. `qa/memory/INDEX.md`    — Index of all memory files; load this before selecting which files to read.
+1. `qa/README.md`          - The Living Index: module status, sprint history, blockers, quick-start commands.
+2. `qa/memory/INDEX.md`    - Index of all memory files; load this before selecting which files to read.

package/templates/qa-framework.rules.md

@@ -0,0 +1,53 @@
+# QA Framework Instructions
+
+This project uses `@keber/qa-framework` v{{VERSION}} for spec-driven automated testing.
+
+## Agent behavior rules
+
+0. **On every conversation start:** check if `qa/AGENT-NEXT-STEPS.md` exists. If it does, read it and complete its steps before anything else.
+1. Before performing any QA task, run the corresponding `/qa-{name}` command (see `.claude/commands/`), which loads the relevant skill via `.github/skills/qa-{name}/SKILL.md`. For project context, read `qa/memory/INDEX.md` if it exists, then load only the memory files relevant to the current task - do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
+2. Always save artifacts in the correct `qa/` subfolder - refer to `qa/QA-STRUCTURE-GUIDE.md`
+3. Never hardcode credentials - always use env vars and `<PLACEHOLDER>` in documentation
+4. Follow the naming conventions in `qa/00-standards/naming-conventions.md`
+5. Read previous test suites code in `qa/07-automation/e2e/tests/` if available before writing new automation to maintain consistency in style and approach
+6. Project QA config is at `qa/qa-framework.config.json`
+7. Save learnings in `qa/memory/` with proper naming and metadata. Always update `qa/memory/INDEX.md` after adding or updating any memory file.
+8. **Sprint/module completion criteria:** A sprint or module is complete when every TC in scope has one of these three valid states - and no other: (a) `test()` passing: the app meets the spec; (b) `test.fail()`: the app violates the spec **and** a file `qa/06-defects/open/DEF-SIS-NNN_*.md` exists documenting which business rule is violated and what the app actually does; (c) `test.skip()`: the TC is not yet executable, annotated with `PENDING-CODE` and a linked issue. A sprint is **not** complete if any TC is failing without `test.fail()`, or has `test.fail()` without a defect file, or has `test.skip()` without a `PENDING-CODE` reason.
+9. **On sprint/module completion:** (1) update the module status row in `qa/README.md`; (2) move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`; (3) trim `AGENT-NEXT-STEPS.md` so it contains only the next sprint - never let it accumulate more than one active sprint.
+10. **Assertion polarity rule (BLOCKING):** A test must assert what the **spec** requires, not what the app currently does. If the app fails to meet the spec, use `test.fail()` + correct assertion to document the defect - **never invert or weaken an assertion to make a test go green.** A failing test that exposes a real defect is always more valuable than a passing test that hides one.
+11. **Character encoding safety (BLOCKING):** In ALL generated content (markdown, scripts, test titles, ADO fields, config files), never use characters at these Unicode code points: em-dash (U+2014), en-dash (U+2013), horizontal ellipsis (U+2026), smart/curly quotes (U+201C, U+201D, U+2018, U+2019), or directional arrows (U+2190-U+21FF). Use ASCII equivalents instead: ` - ` (hyphen with surrounding spaces) for dashes, `...` for ellipsis, `"` and `'` for quotes, `->` and `<-` for arrows. Exception: Latin Extended characters (U+00C0-U+024F) are always permitted - this covers Spanish vowels with accents (U+00E0-U+00FA), n with tilde (U+00F1/U+00D1), and u/o with umlaut (U+00FC/U+00DC, U+00F6/U+00D6).
+
+## Formatting rules for generated content
+1. Generate the output in `UTF-8` encoding without BOM (`UTF-8`, no signature).
+2. Ensure the raw output is `UTF-8` encoded with no `EF BB BF` bytes at the beginning.
+
+## Azure DevOps integration
+
+Before any ADO operation, check if `.github/skills/ado-qa/` exists or if
+`integrations.azureDevOps.enabled` is `true` in `qa/qa-framework.config.json`. If either
+condition is met, run `/qa-ado-integration` (see `.claude/commands/`), which loads
+`.github/skills/qa-ado-integration/SKILL.md`, and use it for all ADO interactions
+(work items, test plans, test cases, bugs, etc.).
+
+> To enable Azure DevOps integration run: `npm install github:keber/ado-qa`
+
+## QA Pipeline
+
+Stages must run in order. Never start a stage unless its prerequisite is met.
+
+| Stage | Task | Command | Prerequisite |
+|---|---|---|---|
+| 1 | Analyze module | `/qa-module-analysis` | None |
+| 2 | Generate specifications | `/qa-spec-generation` | 00-inventory.md exists |
+| 3 | Generate test plan | `/qa-test-plan` | 05-test-scenarios.md exists |
+| 4 | Generate test cases | `/qa-test-cases` | Test plan exists |
+| 5 | Generate automation | `/qa-automation` | Specs approved, no PENDING-CODE |
+| 5b | Stabilize failing tests | `/qa-test-stabilization` | Failing tests exist |
+| 6 | Maintenance | `/qa-maintenance` | Application change delivered |
+| - | ADO integration | `/qa-ado-integration` | ADO enabled in config |
+
+Each command reads its full skill from `.github/skills/qa-{name}/SKILL.md` before acting - see `.claude/commands/` for the generated wrappers.
+
+## Project KB
+1. `qa/README.md`          - The Living Index: module status, sprint history, blockers, quick-start commands.
+2. `qa/memory/INDEX.md`    - Index of all memory files; load this before selecting which files to read.