@keber/qa-framework 1.9.1 → 1.11.3

package/integrations/playwright/README.md

@@ -66,3 +66,127 @@ test.describe('[TC-M-S-NNN] Module > Submodule @P0', () => {
   });
 });
 ```
+
+## Visual AI helper (optional advanced pattern)
+
+> **Advanced / optional.** This pattern is not part of the default scaffold and requires
+> an AI vision API key. Use it when a selector-based assertion is too brittle or the
+> element structure changes frequently (e.g. PDF previews, dashboard charts, export outputs).
+
+Instead of asserting specific selectors, take a screenshot and ask an AI vision model to
+verify that the expected content is visually present. This decouples the assertion from DOM
+structure and is useful for generated documents or complex layouts.
+
+```typescript
+// fixtures/vision-helper.ts
+import * as https from 'https';
+
+export interface VisionResult {
+  passes: boolean;
+  reason: string;
+  raw?: string;
+}
+
+/**
+ * Sends a screenshot to an AI vision model and asks whether the described
+ * content is visually present. Degrades gracefully when the API key is absent.
+ *
+ * Requires an API key in the environment (e.g. OPENAI_API_KEY for GPT-4o,
+ * or adapt the request body for any other vision-capable model).
+ */
+export async function assertScreenshotShowsContent(
+  screenshotBuffer: Buffer,
+  contentDescription: string,
+  options: { model?: string; degradeOnMissingKey?: boolean } = {}
+): Promise<VisionResult> {
+  const apiKey = process.env.AI_VISION_API_KEY;
+  const degrade = options.degradeOnMissingKey ?? true;
+
+  if (!apiKey) {
+    if (degrade) {
+      console.warn('[vision-helper] AI_VISION_API_KEY not set. Skipping visual assertion.');
+      return { passes: true, reason: 'SKIPPED: AI_VISION_API_KEY not configured' };
+    }
+    return { passes: false, reason: 'AI_VISION_API_KEY not set in environment' };
+  }
+
+  const base64Image = screenshotBuffer.toString('base64');
+  const model = options.model ?? 'gpt-4o';
+
+  const prompt = `You are a QA assistant verifying screenshots of a web application.
+Answer YES or NO: Does the screenshot clearly show ${contentDescription}?
+Reply in exactly this format:
+VERDICT: YES
+REASON: <one short sentence>`;
+
+  const body = JSON.stringify({
+    model,
+    max_tokens: 150,
+    messages: [{
+      role: 'user',
+      content: [
+        { type: 'text', text: prompt },
+        { type: 'image_url', image_url: { url: `data:image/png;base64,${base64Image}`, detail: 'low' } },
+      ],
+    }],
+  });
+
+  const raw = await new Promise<string>((resolve, reject) => {
+    const req = https.request({
+      hostname: 'api.openai.com',
+      path: '/v1/chat/completions',
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${apiKey}`,
+        'Content-Length': Buffer.byteLength(body),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', (chunk) => { data += chunk; });
+      res.on('end', () => resolve(data));
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+
+  const parsed = JSON.parse(raw);
+  const text: string = parsed.choices?.[0]?.message?.content ?? '';
+  const verdict = text.match(/VERDICT:\s*(YES|NO)/i);
+  const reason  = text.match(/REASON:\s*(.+)/i);
+
+  if (!verdict) return { passes: false, reason: `Unexpected response: ${text}`, raw: text };
+  return {
+    passes: verdict[1].toUpperCase() === 'YES',
+    reason: reason?.[1]?.trim() ?? text,
+    raw: text,
+  };
+}
+```
+
+**Usage in a test:**
+
+```typescript
+import { assertScreenshotShowsContent } from '../fixtures/vision-helper';
+
+test('[TC-MOD-001] Export PDF contains expected content', async ({ page }) => {
+  // ... trigger export ...
+  const screenshot = await page.screenshot();
+  const result = await assertScreenshotShowsContent(
+    screenshot,
+    'a completed export confirmation message with a download link'
+  );
+  expect(result.passes, result.reason).toBe(true);
+});
+```
+
+**Setup notes:**
+
+- Copy `vision-helper.ts` into your `fixtures/` directory.
+- Set `AI_VISION_API_KEY` in your `.env` file (not committed). The example uses the OpenAI
+  API; adapt the request body for any other vision model.
+- By default, the helper degrades to a skip (passes: true) when the key is absent, so CI
+  runs without the key do not fail on this assertion.
+- `pdf-parse` (v2+) exports a `PDFParse` class rather than a function. Use
+  `new PDFParse({ data: buffer })` and call `.getText()` on the instance.

package/integrations/playwright-azure-reporter/README.md

@@ -1,4 +1,4 @@
-# Integration — playwright-azure-reporter
+# Integration - playwright-azure-reporter
 
 Connects Playwright test results to Azure DevOps Test Plans automatically.
 
@@ -8,42 +8,98 @@ Connects Playwright test results to Azure DevOps Test Plans automatically.
 npm install --save-dev @alex_neo/playwright-azure-reporter
 ```
 
-## Required environment variables
+## Environment variables
+
+### Local development (`.env`)
 
 ```
-ADO_ORG_URL=https://dev.azure.com/your-org
-ADO_PROJECT_NAME=YourProject
+ADO_ORG=<org-slug>
+ADO_PROJECT=<project-name>
 ADO_PLAN_ID=<plan-id>
-AZURE_TOKEN=<personal-access-token>
+AZURE_TOKEN=<personal-access-token> # PAT with Test Management: Read & Write
+```
+
+> NEVER commit `.env` files to source control.
+
+### CI/CD pipeline (`QA-Variables` Library Variable Group)
+
+In the pipeline, `SYSTEM_ACCESSTOKEN` (OAuth) is used instead of a PAT -
+no `AZURE_TOKEN` is needed. The reporter accepts both authentication methods.
+
+```
+ADO_ORG=<org-slug>
+ADO_PROJECT=<project-name>
+ADO_E2E_PLAN_ID=<plan-id>
+ADO_API_PLAN_ID=<plan-id>
 ```
 
-> These variables MUST be injected via CI secrets (Azure Pipeline Library Variable Group).
-> NEVER store tokens in `.env` files committed to source control.
+`SYSTEM_ACCESSTOKEN` is injected automatically by the pipeline via `$(System.AccessToken)`.
 
 ## playwright.config.ts snippet
 
 ```typescript
-import type { PlaywrightTestConfig } from '@playwright/test';
+import { defineConfig } from '@playwright/test';
 
-const config: PlaywrightTestConfig = {
+export default defineConfig({
   reporter: [
     ['list'],
     ['html', { open: 'never' }],
     ['@alex_neo/playwright-azure-reporter', {
-      token:           process.env.AZURE_TOKEN!,
-      planId:          Number(process.env.ADO_PLAN_ID),
-      projectName:     process.env.ADO_PROJECT_NAME!,
-      orgUrl:          process.env.ADO_ORG_URL!,
-      testRunTitle:    `[Automated] ${new Date().toISOString().slice(0, 10)}`,
+      token:                   process.env.SYSTEM_ACCESSTOKEN ?? process.env.AZURE_TOKEN!,
+      planId:                  Number(process.env.ADO_PLAN_ID),
+      projectName:             process.env.ADO_PROJECT!,
+      orgUrl:                  `https://dev.azure.com/${process.env.ADO_ORG}`,
+      testRunTitle:            `[Automated] ${new Date().toISOString().slice(0, 10)}`,
       publishResultsOnFailure: true,
-      isDisabled:      process.env.ADO_SYNC_DISABLED === 'true',
     }],
   ],
-};
+});
+```
+
+> `token` falls back to `AZURE_TOKEN` when `SYSTEM_ACCESSTOKEN` is not present (local runs).
+
+## Playwright Workspaces reporter (optional)
+
+To also publish results to the Azure Playwright Workspaces dashboard, add
+`@azure/playwright` alongside `@alex_neo/playwright-azure-reporter`.
 
-export default config;
+```bash
+npm install --save-dev @azure/playwright
 ```
 
+Create a `playwright.service.config.ts` file next to `playwright.config.ts`:
+
+```typescript
+import { defineConfig } from '@playwright/test';
+import { createAzurePlaywrightConfig } from '@azure/playwright';
+import { DefaultAzureCredential } from '@azure/identity';
+import config from './playwright.config';
+
+export default defineConfig(
+  config,
+  createAzurePlaywrightConfig(config, {
+    credential: new DefaultAzureCredential(),
+  })
+);
+```
+
+Run using the service config in CI:
+
+```bash
+npx playwright test -c playwright.service.config.ts
+```
+
+Required variable (add to `QA-Variables` Library Variable Group):
+
+```
+PLAYWRIGHT_SERVICE_URL=<workspace-endpoint-url>   # Azure Portal -> Playwright workspace -> Get Started
+```
+
+Authentication uses Microsoft Entra ID via the pipeline's Azure service connection
+(`AzureCLI@2` login task). No `PLAYWRIGHT_SERVICE_ACCESS_TOKEN` is needed when
+Entra ID is configured. See `pipelines/azure-pipeline-qa.yml` for the commented
+placeholder steps.
+
 ## Test case title format (required for ADO sync)
 
 The reporter matches test titles to ADO Work Items by the numeric prefix.
@@ -73,16 +129,11 @@ file/describe block to its ADO Test Suite. Example:
 }
 ```
 
-## Disabling ADO sync locally
-
-Set `ADO_SYNC_DISABLED=true` in your `.env` to skip reporting while running
-tests locally.
-
 ## Troubleshooting
 
 | Symptom | Cause | Fix |
 |---------|-------|-----|
-| `401 Unauthorized` | Expired PAT | Regenerate PAT in ADO → User Settings |
+| `401 Unauthorized` (local) | Expired PAT | Regenerate PAT in ADO -> User Settings |
+| `401 Unauthorized` (pipeline) | `SYSTEM_ACCESSTOKEN` not passed | Verify `env: SYSTEM_ACCESSTOKEN: $(System.AccessToken)` in the pipeline step |
 | `Test case not found` | WI ID mismatch | Re-run `inject-ado-ids.ps1` |
-| Results not published | `isDisabled: true` | Remove or set to `false` |
 | Duplicate test runs | Reporter called twice | Check for duplicate reporter arrays |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.9.1",
+  "version": "1.11.3",
   "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
   "keywords": [
     "qa",
@@ -38,10 +38,9 @@
   "engines": {
     "node": ">=18"
   },
-  "devDependencies": {},
   "peerDependencies": {
-    "@playwright/test": ">=1.40.0",
-    "@keber/ado-qa": ">=1.0.0"
+    "@keber/ado-qa": ">=1.0.0",
+    "@playwright/test": ">=1.40.0"
   },
   "peerDependenciesMeta": {
     "@playwright/test": {

package/qa-framework.config.json

@@ -1,6 +1,6 @@
 {
   "$schema": "./qa-framework.config.schema.json",
-  "frameworkVersion": "1.1.3",
+  "frameworkVersion": "1.10.0",
 
   "project": {
     "name": "{{PROJECT_NAME}}",

package/scripts/init.js

@@ -84,6 +84,7 @@ const topLevelFolders = [
   '04-test-data',
   '05-test-execution',
   '06-defects/open',
+  '06-defects/disputed',
   '06-defects/resolved',
   '07-automation/e2e/tests',
   '07-automation/e2e/tests/helpers/debug',
@@ -98,6 +99,18 @@ for (const folder of topLevelFolders) {
   console.log(`  [created] ${path.relative(cwd, fullPath)}/`);
 }
 
+// --- 06-defects/disputed/README.md ---
+writeIfMissing(path.join(qaRoot, '06-defects', 'disputed', 'README.md'),
+`# 06-defects/disputed/
+
+Use this folder for defects where QA has reproducible evidence but the business or
+development team disputes whether the observed behavior is actually a defect.
+
+A defect stays here while the functional decision is pending. Once the team reaches
+a formal conclusion, move the file to open/ (confirmed defect) or resolved/ (accepted
+behavior or won't fix).
+`);
+
 // --- qa/README.md ---
 const qaReadmeTemplate = path.resolve(__dirname, '..', 'templates', 'qa-readme.md');
 if (fs.existsSync(qaReadmeTemplate)) {
@@ -120,10 +133,17 @@ writeIfMissing(path.join(memoryDir, 'INDEX.md'),
 
 | File | Topic | When to load |
 |---|---|---|
-
-_No memory files yet. Add files to this directory and register them above._
+| \`ci-pipeline-findings.md\` | CI pipeline issues, root causes, applied fixes, failure triage categories | Diagnosing CI failures; reviewing pipeline changes |
+| \`e2e-stabilization-patterns.md\` | Flakiness patterns, crash-recovery techniques, strict-mode conflicts, reference timeouts | Investigating intermittent failures; refactoring fragile specs |
+| \`data-volatility-strategies.md\` | Strategies for handling volatile test data (filter values, row counts, search inputs) | Fixing hardcoded-data failures; choosing an assertion resilience approach |
 `);
 
+// --- qa/memory template files ---
+const memorySrc = path.resolve(__dirname, '..', 'templates', 'memory');
+for (const file of ['ci-pipeline-findings.md', 'e2e-stabilization-patterns.md', 'data-volatility-strategies.md']) {
+  writeIfMissing(path.join(memoryDir, file), fs.readFileSync(path.join(memorySrc, file), 'utf8'));
+}
+
 // --- 03-test-cases README (optional directory marker) ---
 writeIfMissing(path.join(qaRoot, '03-test-cases', 'README.md'),
 `# 03-test-cases/ — Optional Standalone Test Cases
@@ -227,7 +247,7 @@ for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', '
 }
 const fixturesDir = path.join(e2eScaffoldDir, 'fixtures');
 fs.mkdirSync(fixturesDir, { recursive: true });
-for (const file of ['auth.ts', 'test-helpers.ts']) {
+for (const file of ['auth.ts', 'test-helpers.ts', 'base.ts']) {
   const dest = path.join(fixturesDir, file);
   if (!fs.existsSync(dest)) {
     fs.copyFileSync(path.join(scaffoldSrc, 'fixtures', file), dest);
@@ -235,9 +255,26 @@ for (const file of ['auth.ts', 'test-helpers.ts']) {
   }
 }
 
-// --- Integration + Load test placeholders ---
-writeIfMissing(path.join(automationDir, 'integration', 'README.md'),
-`# Integration Tests\n\n> Placeholder for API/integration tests (k6, JMeter, Azure Load Testing, etc.).\n> Each tool gets its own subdirectory.\n`);
+// --- Integration scaffold (lives in 07-automation/integration/) ---
+const integrationDir      = path.join(automationDir, 'integration');
+const integrationScaffold = path.resolve(__dirname, '..', 'templates', 'integration-scaffold');
+fs.mkdirSync(integrationDir, { recursive: true });
+for (const file of ['package.json', 'playwright.config.ts', 'global-setup.ts', 'README.md', '.env.example']) {
+  const dest = path.join(integrationDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(integrationScaffold, file), dest);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
+  }
+}
+const integrationTestsDir = path.join(integrationDir, 'tests');
+fs.mkdirSync(integrationTestsDir, { recursive: true });
+const exampleSpec = path.join(integrationTestsDir, 'example.spec.ts');
+if (!fs.existsSync(exampleSpec)) {
+  fs.copyFileSync(path.join(integrationScaffold, 'tests', 'example.spec.ts'), exampleSpec);
+  console.log(`  [created] ${path.relative(cwd, exampleSpec)}`);
+}
+
+// --- Load test placeholder ---
 writeIfMissing(path.join(automationDir, 'load', 'README.md'),
 `# Load Tests\n\n> Placeholder for load and performance tests.\n> Each tool gets its own subdirectory (e.g. k6/, jmeter/).\n`);
 
@@ -272,37 +309,9 @@ if (fs.existsSync(structureGuideSrc)) {
 const githubDir         = path.join(cwd, '.github');
 const copilotInstrPath  = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
 
-// Detect whether the ado-qa skill is available (installed or already copied)
-const adoQaInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@keber', 'ado-qa'))
-                    || fs.existsSync(path.join(cwd, 'node_modules', 'ado-qa'));
-const adoSkillReady  = fs.existsSync(path.join(cwd, '.github', 'skills', 'ado-qa'));
-const adoAvailable   = adoQaInstalled || adoSkillReady;
-
-const adoSection = adoAvailable
-  ? `## Azure DevOps integration (ado-qa)
-
-The \`ado-qa\` skill is installed. Load it in PowerShell before any ADO operation:
-\`\`\`powershell
-. .github/skills/ado-qa/load.ps1
-\`\`\`
-Refer to \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` for the full ADO workflow.
-
-`
-  : `## Azure DevOps integration (not installed)
-
-> ⚠️ **Agent note:** \`ado-qa\` is not installed in this project.
-> To enable Azure DevOps integration (query Work Items, Test Plans, create bugs, etc.) run:
-> \`\`\`bash
-> npm install github:keber/ado-qa
-> \`\`\`
-> This will automatically copy the ADO skills to \`.github/skills/\` via postinstall.
-
-`;
-
 const instrTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.instructions.md');
 const copilotInstrContent = fs.readFileSync(instrTemplatePath, 'utf8')
-  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0')
-  .replace('{{ADO_SECTION}}', adoSection);
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
 // --- AGENT-NEXT-STEPS.md — readable by the agent after install ---
@@ -328,15 +337,21 @@ Edit \`qa/qa-framework.config.json\` and add your project modules under the \`"m
 npm install @keber/ado-qa
 \`\`\`
 
-**Playwright automation:**
+**Playwright E2E automation:**
 \`\`\`bash
 npm install @playwright/test
 cd qa/07-automation/e2e && npm install && npx playwright install chromium
 \`\`\`
 
+**Playwright API/integration automation:**
+\`\`\`bash
+cd qa/07-automation/integration && npm install
+\`\`\`
+
 ### 3. Credentials
-- Copy \`qa/07-automation/e2e/.env.example\` → \`qa/07-automation/e2e/.env\` and fill in credentials
-- Add \`qa/07-automation/e2e/.env\` and \`qa/07-automation/e2e/.auth/\` to \`.gitignore\`
+- Copy \`qa/07-automation/e2e/.env.example\` -> \`qa/07-automation/e2e/.env\` and fill in credentials
+- Copy \`qa/07-automation/integration/.env.example\` -> \`qa/07-automation/integration/.env\` and fill in credentials
+- Add both \`.env\` files and both \`.auth/\` folders to \`.gitignore\`
 `;
 const nextStepsPath = path.join(qaRoot, 'AGENT-NEXT-STEPS.md');
 writeIfMissing(nextStepsPath, nextStepsContent);

package/scripts/upgrade.js

@@ -93,8 +93,7 @@ if (!fs.existsSync(skillsSrc)) {
 const copilotInstrPath = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
 const instrTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.instructions.md');
 const copilotContent = fs.readFileSync(instrTemplatePath, 'utf8')
-  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0')
-  .replace('{{ADO_SECTION}}', '');
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
 forceWrite(copilotInstrPath, copilotContent);
 
 // ---------------------------------------------------------------------------
@@ -175,6 +174,22 @@ for (const file of scaffoldFiles) {
   }
 }
 
+// 5a.1. Ensure the refreshed fixtures scaffold exists.
+const scaffoldFixturesDir = path.join(e2eDir, 'fixtures');
+const fixtureFiles = ['auth.ts', 'test-helpers.ts', 'base.ts'];
+for (const file of fixtureFiles) {
+  const oldPath = path.join(automationDir, 'fixtures', file);
+  const newPath = path.join(scaffoldFixturesDir, file);
+  if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+    if (!dryRun) {
+      fs.mkdirSync(scaffoldFixturesDir, { recursive: true });
+      fs.renameSync(oldPath, newPath);
+    }
+    updated.push(newPath);
+    console.log(`  [migrated] fixtures/${file} -> e2e/fixtures/${file}`);
+  }
+}
+
 // 5b. fixtures/: 07-automation/fixtures/ -> 07-automation/e2e/fixtures/
 const oldFixturesDir = path.join(automationDir, 'fixtures');
 const newFixturesDir = path.join(e2eDir, 'fixtures');
@@ -211,17 +226,34 @@ if (fs.existsSync(e2eDir)) {
   }
 }
 
-// 5d. Create integration/ and load/ placeholders if missing.
-const integrationReadme = path.join(automationDir, 'integration', 'README.md');
-const loadReadme        = path.join(automationDir, 'load', 'README.md');
+// 5d. Create integration scaffold if missing (uses template; existing files are never overwritten).
+const integrationDir      = path.join(automationDir, 'integration');
+const integrationScaffold = path.resolve(__dirname, '..', 'templates', 'integration-scaffold');
+const integrationReadme   = path.join(integrationDir, 'README.md');
+const loadReadme          = path.join(automationDir, 'load', 'README.md');
 if (!fs.existsSync(integrationReadme)) {
   if (!dryRun) {
-    fs.mkdirSync(path.dirname(integrationReadme), { recursive: true });
-    fs.writeFileSync(integrationReadme,
-      '# Integration Tests\n\n> Placeholder for API/integration tests (k6, JMeter, Azure Load Testing, etc.).\n> Each tool gets its own subdirectory.\n', 'utf8');
+    fs.mkdirSync(integrationDir, { recursive: true });
+    for (const file of ['package.json', 'playwright.config.ts', 'global-setup.ts', 'README.md', '.env.example']) {
+      const dest = path.join(integrationDir, file);
+      if (!fs.existsSync(dest)) {
+        fs.copyFileSync(path.join(integrationScaffold, file), dest);
+        updated.push(dest);
+        console.log(`  [created] ${path.relative(cwd, dest)}`);
+      }
+    }
+    const integrationTestsDir = path.join(integrationDir, 'tests');
+    fs.mkdirSync(integrationTestsDir, { recursive: true });
+    const exampleSpec = path.join(integrationTestsDir, 'example.spec.ts');
+    if (!fs.existsSync(exampleSpec)) {
+      fs.copyFileSync(path.join(integrationScaffold, 'tests', 'example.spec.ts'), exampleSpec);
+      updated.push(exampleSpec);
+      console.log(`  [created] ${path.relative(cwd, exampleSpec)}`);
+    }
+  } else {
+    updated.push(integrationReadme);
+    console.log(`  [created] ${path.relative(cwd, integrationReadme)}`);
   }
-  updated.push(integrationReadme);
-  console.log(`  [created] ${path.relative(cwd, integrationReadme)}`);
 }
 if (!fs.existsSync(loadReadme)) {
   if (!dryRun) {
@@ -346,6 +378,69 @@ if (!fs.existsSync(testCasesReadme)) {
   console.log(`  [created] 03-test-cases/README.md`);
 }
 
+// ---------------------------------------------------------------------------
+// 7. Ensure 06-defects/disputed/ exists (added in v1.11.0)
+//    Safe: only creates if missing. Never touches existing files.
+// ---------------------------------------------------------------------------
+const defectsDir   = path.join(qaRoot, '06-defects');
+const disputedDir  = path.join(defectsDir, 'disputed');
+const disputedReadme = path.join(disputedDir, 'README.md');
+
+if (fs.existsSync(defectsDir) && !fs.existsSync(disputedDir)) {
+  if (!dryRun) {
+    fs.mkdirSync(disputedDir, { recursive: true });
+    fs.writeFileSync(disputedReadme,
+`# 06-defects/disputed/
+
+Use this folder for defects where QA has reproducible evidence but the business or
+development team disputes whether the observed behavior is actually a defect.
+
+A defect stays here while the functional decision is pending. Once the team reaches
+a formal conclusion, move the file to open/ (confirmed defect) or resolved/ (accepted
+behavior or won't fix).
+`, 'utf8');
+  }
+  updated.push(disputedDir);
+  console.log(`  [created] 06-defects/disputed/`);
+  console.log(`  [created] 06-defects/disputed/README.md`);
+} else if (!fs.existsSync(disputedReadme) && fs.existsSync(disputedDir)) {
+  if (!dryRun) {
+    fs.writeFileSync(disputedReadme,
+`# 06-defects/disputed/
+
+Use this folder for defects where QA has reproducible evidence but the business or
+development team disputes whether the observed behavior is actually a defect.
+
+A defect stays here while the functional decision is pending. Once the team reaches
+a formal conclusion, move the file to open/ (confirmed defect) or resolved/ (accepted
+behavior or won't fix).
+`, 'utf8');
+  }
+  updated.push(disputedReadme);
+  console.log(`  [created] 06-defects/disputed/README.md`);
+}
+
+// ---------------------------------------------------------------------------
+// 8. Seed qa/memory/ template files if missing (added in v1.11.0)
+//    Safe: only creates files that do not exist. Never overwrites user content.
+// ---------------------------------------------------------------------------
+const memoryDir = path.join(qaRoot, 'memory');
+if (fs.existsSync(memoryDir)) {
+  const memorySrc = path.resolve(__dirname, '..', 'templates', 'memory');
+  for (const file of ['ci-pipeline-findings.md', 'e2e-stabilization-patterns.md', 'data-volatility-strategies.md']) {
+    const dest = path.join(memoryDir, file);
+    if (!fs.existsSync(dest)) {
+      if (!dryRun) {
+        fs.copyFileSync(path.join(memorySrc, file), dest);
+      }
+      updated.push(dest);
+      console.log(`  [created] memory/${file}`);
+    } else {
+      skipped.push(dest);
+    }
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------

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

@@ -1,4 +1,4 @@
-# -----------------------------------------------------------------------
+# -----------------------------------------------------------------------
 # keber/qa-framework — Environment Variables Reference
 # -----------------------------------------------------------------------
 # Copy this file to .env and fill in real values.
@@ -10,6 +10,20 @@
 # -----------------------------------------------------------------------
 QA_BASE_URL=https://your-app.qa.example.com
 
+# -----------------------------------------------------------------------
+# Session and login resilience
+# -----------------------------------------------------------------------
+QA_SESSION_TTL_MS=7200000
+# Optional path to a server-side logout endpoint if the app exposes one.
+# QA_LOGOUT_PATH=/logout
+
+# When parallel user mode is enabled, limit auth to the matching project(s).
+# QA_AUTH_USER=1
+
+# Optional second test user for 2-project parallel execution.
+# QA_USER2_EMAIL=qa-user2@example.com
+# QA_USER2_PASSWORD=CHANGE_ME
+
 # -----------------------------------------------------------------------
 # Login Configuration
 # These selectors allow the framework to work with any login form.
@@ -54,3 +68,8 @@ QA_USER_PASSWORD=CHANGE_ME
 # -----------------------------------------------------------------------
 # CI=true           # Set automatically by most CI systems
 # ADO_SYNC_DISABLED=false   # Set to true to skip ADO reporter in local runs
+
+# -----------------------------------------------------------------------
+# Playwright Service  (optional - only needed for cloud or self-hosted grid)
+# -----------------------------------------------------------------------
+# PLAYWRIGHT_SERVICE_URL=wss://eastus.api.playwright.microsoft.com/accounts/<your-id>/browsers