ai-control-center 1.15.2

package/lib/actions/status.js

@@ -0,0 +1,47 @@
+import { readFileSync, existsSync, readdirSync } from 'fs';
+import { resolve } from 'path';
+import chalk from 'chalk';
+import { getStatus, getWorkflowDir } from '../utils/pipeline.js';
+import { printDivider } from '../utils/display.js';
+
+export function showStatusAction() {
+  const status = getStatus();
+  const workflowDir = getWorkflowDir();
+
+  console.log('');
+  console.log(chalk.bold('  Pipeline Status'));
+  printDivider();
+  console.log(`  Stage:          ${chalk.bold(status.stage || 'idle')}`);
+  console.log(`  Feature:        ${chalk.cyan(status.current_feature || 'none')}`);
+  console.log(`  Next Step:      ${chalk.yellow(status.next || '—')}`);
+
+  if (status.latest_spec)   console.log(`  Latest Spec:    ${chalk.dim(status.latest_spec)}`);
+  if (status.latest_arch)   console.log(`  Latest Arch:    ${chalk.dim(status.latest_arch)}`);
+  if (status.latest_tasks)  console.log(`  Latest Tasks:   ${chalk.dim(status.latest_tasks)}`);
+  if (status.latest_review) console.log(`  Latest Review:  ${chalk.dim(status.latest_review)}`);
+
+  printDivider();
+
+  // Show recent files in each directory
+  const dirs = ['inbox', 'specs', 'architecture', 'tasks', 'reviews', 'approved', 'rejected'];
+  dirs.forEach(dir => {
+    const fullDir = resolve(workflowDir, dir);
+    if (!existsSync(fullDir)) return;
+    const files = readdirSync(fullDir).filter(f => f.endsWith('.md')).sort().reverse().slice(0, 1);
+    if (files.length) {
+      console.log(`  ${dir.padEnd(15)} ${chalk.dim(files[0])}`);
+    }
+  });
+
+  // History
+  if (status.history && status.history.length) {
+    console.log('');
+    console.log(chalk.bold('  History'));
+    printDivider();
+    status.history.slice(-5).reverse().forEach(h => {
+      console.log(`  ${chalk.dim(h.time || '')}  ${chalk.cyan(h.id || '')}  →  ${h.stage}`);
+    });
+  }
+
+  console.log('');
+}

package/lib/agents/browser-qa-agent.js

@@ -0,0 +1,611 @@
+/**
+ * Browser QA Agent — Playwright-based autonomous web tester.
+ *
+ * Logs into target website as a test user, crawls all discoverable routes,
+ * tests interactive elements, captures screenshots, and generates a
+ * structured JSON report for the Bug-Fixer Agent to consume.
+ *
+ * Called by: lib/actions/browser-test.js (pipeline stage wrapper)
+ * Output:    .ai-workflow/qa-reports/QA-{timestamp}.json
+ *            .ai-workflow/screenshots/{slug}.png
+ */
+
+import { chromium } from 'playwright';
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'fs';
+import { resolve } from 'path';
+import { getWorkflowDir, updateStatus } from '../utils/pipeline.js';
+import { logActivity } from '../utils/activity-log.js';
+import { ScreenshotStore } from '../integrations/screenshot-store.js';
+import { isExcluded as _isExcluded, isFormSafe, isSessionExpired, resolveCredentials } from '../utils/security.js';
+
+// Local alias + re-export for testing convenience
+const isExcluded = _isExcluded;
+export { isExcluded };
+
+// ─── Config defaults ──────────────────────────────────────────────────────────
+
+const DEFAULT_TIMEOUT     = 15_000;
+const DEFAULT_NAV_TIMEOUT = 30_000;
+const MAX_ROUTES          = 80;
+const INTERACTIVE_TAGS    = ['button', 'a[href]', 'input', 'select', 'textarea', '[role=button]', '[role=link]', '[role=tab]'];
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+function slugify(url) {
+  return url.replace(/https?:\/\//, '').replace(/[^a-z0-9]/gi, '_').slice(0, 80);
+}
+
+function ensureDir(dir) {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+// ─── Page Health Checker ──────────────────────────────────────────────────────
+
+async function checkPageHealth(page, url) {
+  const errors   = [];
+  const warnings = [];
+  const consoleErrors = [];
+
+  page.on('console', msg => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text().slice(0, 200));
+  });
+
+  // Check for broken images
+  const brokenImages = await page.$$eval('img', imgs =>
+    imgs
+      .filter(i => !i.complete || i.naturalWidth === 0)
+      .map(i => i.src)
+  ).catch(() => []);
+
+  if (brokenImages.length > 0) {
+    errors.push(`Broken images (${brokenImages.length}): ${brokenImages.slice(0, 3).join(', ')}`);
+  }
+
+  // Check for missing alt text on images
+  const imagesWithoutAlt = await page.$$eval('img:not([alt])', imgs => imgs.length).catch(() => 0);
+  if (imagesWithoutAlt > 0) {
+    warnings.push(`${imagesWithoutAlt} images missing alt text (accessibility)`);
+  }
+
+  // Check for 404 text in body
+  const bodyText = await page.textContent('body').catch(() => '');
+  if (/404|not found|page not found/i.test(bodyText.slice(0, 500))) {
+    errors.push('Page appears to be a 404 error');
+  }
+
+  // Check for unhandled error overlays (common in React dev)
+  const errorOverlay = await page.$('#webpack-dev-server-client-overlay, [data-reactroot] pre').catch(() => null);
+  if (errorOverlay) {
+    const overlayText = await errorOverlay.textContent().catch(() => '');
+    if (overlayText.trim()) errors.push(`Runtime error overlay: ${overlayText.slice(0, 200)}`);
+  }
+
+  // Add captured console errors
+  if (consoleErrors.length > 0) {
+    errors.push(...consoleErrors.slice(0, 5));
+  }
+
+  return { errors, warnings };
+}
+
+// ─── Login Handler ────────────────────────────────────────────────────────────
+
+async function loginToWebsite(page, credentials) {
+  const { loginUrl, email, password, loginSelectors } = credentials;
+
+  logActivity('QA', `Navigating to login: ${loginUrl}`, 'info');
+  await page.goto(loginUrl, { waitUntil: 'domcontentloaded', timeout: DEFAULT_NAV_TIMEOUT });
+
+  // Normalize selectors — config may provide a single CSS string or an array
+  const toArray = (val, defaults) => {
+    if (!val) return defaults;
+    return Array.isArray(val) ? val : [val];
+  };
+
+  const emailSels = toArray(loginSelectors?.email, [
+    '[type=email]', '[name=email]', '[name=username]',
+    '#email', '#username', 'input[placeholder*="email" i]', 'input[placeholder*="username" i]',
+  ]);
+  const passwordSels = toArray(loginSelectors?.password, [
+    '[type=password]', '[name=password]', '#password',
+    'input[placeholder*="password" i]',
+  ]);
+  const submitSels = toArray(loginSelectors?.submit, [
+    'button:has-text("Log In")', 'button:has-text("Login")', 'button:has-text("Sign in")',
+    '[type=submit]', '[data-testid="login-button"]',
+  ]);
+
+  // ── Step 0: If email input isn't visible yet, click the login/signin nav button
+  //    (handles modal-based login flows where a nav button opens the form)
+  let emailEl = null;
+  for (const sel of emailSels) {
+    emailEl = await page.$(sel).catch(() => null);
+    if (emailEl && await emailEl.isVisible().catch(() => false)) break;
+    emailEl = null;
+  }
+
+  if (!emailEl) {
+    logActivity('QA', 'Email input not visible — looking for login trigger button', 'info');
+    const triggerSelectors = toArray(loginSelectors?.trigger, [
+      'button:has-text("Log In")', 'button:has-text("Login")', 'button:has-text("Sign in")',
+      'a:has-text("Log In")', 'a:has-text("Login")', 'a:has-text("Sign in")',
+      '[data-testid="login-trigger"]', '.login-btn', '#login-btn',
+    ]);
+    for (const sel of triggerSelectors) {
+      const trigger = await page.$(sel).catch(() => null);
+      if (trigger && await trigger.isVisible().catch(() => false)) {
+        logActivity('QA', `Clicking login trigger: ${sel}`, 'info');
+        await trigger.click();
+        await page.waitForTimeout(1500); // Wait for modal/form to appear
+        break;
+      }
+    }
+
+    // Re-check for email input after clicking trigger
+    for (const sel of emailSels) {
+      emailEl = await page.$(sel).catch(() => null);
+      if (emailEl && await emailEl.isVisible().catch(() => false)) break;
+      emailEl = null;
+    }
+
+    if (!emailEl) {
+      throw new Error('Login failed — email input not found even after clicking login trigger');
+    }
+  }
+
+  // ── Step 1: Fill email
+  await emailEl.fill(email);
+
+  // ── Step 2: Fill password
+  for (const sel of passwordSels) {
+    const el = await page.$(sel).catch(() => null);
+    if (el && await el.isVisible().catch(() => false)) {
+      await el.fill(password);
+      break;
+    }
+  }
+
+  // ── Step 3: Submit (click the form submit button, not the nav trigger)
+  //    Prefer the wider/form submit button over the nav button
+  const allSubmitBtns = [];
+  for (const sel of submitSels) {
+    const els = await page.$$(sel).catch(() => []);
+    allSubmitBtns.push(...els);
+  }
+  // Pick the last matching visible submit button (usually the form one, not the nav one)
+  let submitted = false;
+  for (const btn of allSubmitBtns.reverse()) {
+    if (await btn.isVisible().catch(() => false)) {
+      await btn.click();
+      submitted = true;
+      break;
+    }
+  }
+  if (!submitted) {
+    // Fallback: press Enter on the password field
+    for (const sel of passwordSels) {
+      const el = await page.$(sel).catch(() => null);
+      if (el) { await el.press('Enter'); break; }
+    }
+  }
+
+  // ── Step 4: Wait for login to complete
+  await page.waitForTimeout(3000);
+  await page.waitForLoadState('domcontentloaded', { timeout: DEFAULT_NAV_TIMEOUT }).catch(() => {});
+
+  const currentUrl = page.url();
+
+  // Check if login succeeded by multiple signals:
+  // 1. URL changed away from login page
+  // 2. Login modal/form is no longer visible (SPA may not change URL)
+  // 3. An auth token cookie or localStorage was set
+  const isLoginUrl = currentUrl.includes('login') || currentUrl.includes('signin');
+
+  if (isLoginUrl) {
+    // SPA might stay on /login but close the modal after successful auth.
+    // Check if the email input is still visible — if not, login likely succeeded.
+    let emailStillVisible = false;
+    for (const sel of emailSels) {
+      const el = await page.$(sel).catch(() => null);
+      if (el && await el.isVisible().catch(() => false)) {
+        emailStillVisible = true;
+        break;
+      }
+    }
+
+    if (emailStillVisible) {
+      // Check for error messages in the page
+      const errorTexts = await page.$$eval(
+        '[class*="error"], [class*="toast"], [role="alert"], .text-red-500, .text-red-400',
+        els => els.map(e => e.textContent.trim()).filter(t => t.length > 0 && t.length < 200)
+      ).catch(() => []);
+
+      const errMsg = errorTexts.length > 0
+        ? `Errors: ${errorTexts.join('; ')}`
+        : 'No error message found';
+      throw new Error(`Login failed — form still visible. URL: ${currentUrl}. ${errMsg}`);
+    }
+
+    // Modal closed but URL unchanged — SPA login success
+    logActivity('QA', `Login successful (SPA — URL unchanged). Navigating to target...`, 'success');
+    // Navigate to the main page since the SPA didn't redirect
+    await page.goto(loginUrl.replace(/\/login.*$/, '/'), { waitUntil: 'domcontentloaded', timeout: DEFAULT_NAV_TIMEOUT }).catch(() => {});
+    await page.waitForTimeout(1000);
+    logActivity('QA', `Landed on: ${page.url()}`, 'info');
+    return true;
+  }
+
+  logActivity('QA', `Login successful. Landed on: ${currentUrl}`, 'success');
+  return true;
+}
+
+// ─── Route Discoverer ─────────────────────────────────────────────────────────
+
+async function discoverRoutes(page, baseUrl, excludePatterns = []) {
+  const visited = new Set();
+  const toVisit = [baseUrl];
+  const routes  = [];
+  const origin  = new URL(baseUrl).origin;
+
+  while (toVisit.length > 0 && routes.length < MAX_ROUTES) {
+    const url = toVisit.shift();
+    if (visited.has(url)) continue;
+    visited.add(url);
+
+    // V2: Route exclusion check
+    if (isExcluded(url, excludePatterns)) {
+      logActivity('QA', `Excluded route: ${url}`, 'info');
+      continue;
+    }
+
+    try {
+      await page.goto(url, { waitUntil: 'domcontentloaded', timeout: DEFAULT_NAV_TIMEOUT });
+      await page.waitForTimeout(500);
+
+      routes.push(url);
+
+      const links = await page.$$eval('a[href]', (els, orig) =>
+        els
+          .map(el => {
+            try { return new URL(el.href, orig).href; } catch { return null; }
+          })
+          .filter(href =>
+            href &&
+            href.startsWith(orig) &&
+            !href.includes('#') &&
+            !href.match(/\.(pdf|zip|png|jpg|gif|svg|ico|css|js|woff|ttf)$/)
+          ),
+        origin
+      ).catch(() => []);
+
+      for (const link of links) {
+        if (!visited.has(link) && !toVisit.includes(link)) {
+          if (!isExcluded(link, excludePatterns)) {
+            toVisit.push(link);
+          } else {
+            logActivity('QA', `Excluded route: ${link}`, 'info');
+          }
+        }
+      }
+    } catch (err) {
+      logActivity('QA', `Skipping ${url}: ${err.message.slice(0, 80)}`, 'warn');
+    }
+  }
+
+  logActivity('QA', `Discovered ${routes.length} routes`, 'info');
+  return routes;
+}
+
+// ─── Interactive Element Tester ───────────────────────────────────────────────
+
+async function testInteractiveElements(page, url, maxActions = 10) {
+  const issues = [];
+  let actionCount = 0;
+
+  for (const tag of INTERACTIVE_TAGS) {
+    if (actionCount >= maxActions) break;
+    const elements = await page.$$(tag).catch(() => []);
+
+    for (const el of elements.slice(0, maxActions - actionCount)) {
+      actionCount++;
+      try {
+        const isVisible = await el.isVisible().catch(() => false);
+        if (!isVisible) continue;
+
+        const tagName   = await el.evaluate(e => e.tagName.toLowerCase()).catch(() => '');
+        const text      = await el.textContent().catch(() => '');
+        const ariaLabel = await el.getAttribute('aria-label').catch(() => '');
+        const label     = (text || ariaLabel || '').trim().slice(0, 40);
+
+        if (tagName === 'button') {
+          const hasHandler = await el.evaluate(e =>
+            e.onclick !== null || e.getAttribute('data-action') !== null
+          ).catch(() => false);
+
+          if (!label && !hasHandler) {
+            issues.push({ type: 'warning', element: 'button', message: 'Button with no label or handler found' });
+          }
+        }
+
+        if (tagName === 'a') {
+          const href = await el.getAttribute('href').catch(() => '');
+          if (!href || href === '#' || href.startsWith('javascript:void')) {
+            issues.push({ type: 'warning', element: 'a', message: `Dead link: "${label || 'no text'}"` });
+          }
+        }
+
+        if (['input', 'select', 'textarea'].includes(tagName)) {
+          const inputId  = await el.getAttribute('id').catch(() => '');
+          const hasLabel = inputId
+            ? await page.$(`label[for="${inputId}"]`).then(l => !!l).catch(() => false)
+            : false;
+          const hasAria  = await el.getAttribute('aria-label').catch(() => '');
+          if (!hasLabel && !hasAria) {
+            issues.push({ type: 'warning', element: tagName, message: `Form field without label (id: ${inputId || 'none'})` });
+          }
+        }
+      } catch { /* element might be stale */ }
+    }
+  }
+
+  return issues;
+}
+
+// ─── Main QA Runner ───────────────────────────────────────────────────────────
+
+export async function runBrowserQA(config) {
+  const qaConfig = config.browserQA;
+  if (!qaConfig?.enabled) {
+    return { skipped: true, reason: 'browserQA.enabled is false' };
+  }
+
+  const workflowDir   = getWorkflowDir();
+  const screenshotDir = resolve(workflowDir, 'screenshots');
+  const qaReportDir   = resolve(workflowDir, 'qa-reports');
+  ensureDir(screenshotDir);
+  ensureDir(qaReportDir);
+
+  const store     = new ScreenshotStore(screenshotDir);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const report    = {
+    timestamp,
+    targetUrl:   qaConfig.targetUrl,
+    passed:      [],
+    failed:      [],
+    warnings:    [],
+    screenshots: [],
+    summary:     null,
+  };
+
+  logActivity('QA', `Starting browser QA: ${qaConfig.targetUrl}`, 'info');
+  updateStatus({ stage: 'browser-qa', qa_started_at: new Date().toISOString() });
+
+  const browser = await chromium.launch({
+    headless: true,
+    args: ['--no-sandbox', '--disable-setuid-sandbox'],
+  });
+
+  try {
+    const context = await browser.newContext({
+      viewport: { width: 1280, height: 800 },
+      userAgent: 'AICC-QA-Agent/1.0',
+    });
+    const page = await context.newPage();
+
+    // ── 1. Login ──────────────────────────────────────────────────────────────
+    if (qaConfig.credentials) {
+      await loginToWebsite(page, {
+        loginUrl:       qaConfig.credentials.loginUrl || qaConfig.targetUrl + '/login',
+        email:          qaConfig.credentials.email,
+        password:       qaConfig.credentials.password,
+        loginSelectors: qaConfig.credentials.loginSelectors,
+      });
+
+      const loginShot = await store.capture(page, 'after_login', { baseline: true });
+      report.screenshots.push(loginShot);
+    }
+
+    // ── 2. Discover routes (with V2 exclusion patterns) ─────────────────────
+    const excludePatterns = qaConfig.excludeRoutes || [];
+    const routes = await discoverRoutes(page, qaConfig.targetUrl, excludePatterns);
+
+    // ── 3. Test each route (with session expiry + OOM prevention) ────────────
+    let activeBrowser = browser;
+    let activeContext = context;
+    let activePage = page;
+    let routesSinceBrowserRestart = 0;
+    const browserRestartEvery = qaConfig.browserRestartEvery || 30;
+    const maxActionsPerPage = qaConfig.maxActionsPerPage || 10;
+
+    for (const url of routes) {
+      try {
+        // V2: OOM prevention — restart browser every N routes
+        routesSinceBrowserRestart++;
+        if (routesSinceBrowserRestart >= browserRestartEvery) {
+          logActivity('QA', 'Restarting browser to prevent memory leak', 'info');
+          await activeBrowser.close().catch(() => {});
+          activeBrowser = await chromium.launch({
+            headless: true,
+            args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+          });
+          activeContext = await activeBrowser.newContext({
+            viewport: { width: 1280, height: 800 },
+            userAgent: 'AICC-QA-Agent/1.0',
+          });
+          activePage = await activeContext.newPage();
+          // Re-login if needed
+          if (qaConfig.credentials) {
+            await loginToWebsite(activePage, {
+              loginUrl: qaConfig.credentials.loginUrl || qaConfig.targetUrl + '/login',
+              email: qaConfig.credentials.email,
+              password: qaConfig.credentials.password,
+              loginSelectors: qaConfig.credentials.loginSelectors,
+            }).catch(() => {});
+          }
+          routesSinceBrowserRestart = 0;
+        }
+
+        // V3: Pre-flight session check — re-login if current page is already on login
+        const _loginCreds = {
+          loginUrl: qaConfig.credentials?.loginUrl || qaConfig.targetUrl + '/login',
+          email: qaConfig.credentials?.email,
+          password: qaConfig.credentials?.password,
+          loginSelectors: qaConfig.credentials?.loginSelectors,
+        };
+
+        if (qaConfig.credentials && isSessionExpired(activePage.url())) {
+          logActivity('QA', 'Session expired — re-authenticating', 'warn');
+          await loginToWebsite(activePage, _loginCreds).catch(() => {});
+        }
+
+        logActivity('QA', `Testing: ${url}`, 'info');
+        await activePage.goto(url, { waitUntil: 'domcontentloaded', timeout: DEFAULT_NAV_TIMEOUT });
+        await activePage.waitForTimeout(800);
+
+        // V3: Auth-gated route detection — if redirected to login, re-login + retry once.
+        //     If STILL redirected after fresh login, mark as "auth_required" (not a bug).
+        let authGated = false;
+        if (qaConfig.credentials && isSessionExpired(activePage.url())) {
+          logActivity('QA', `Redirected to login on ${url} — re-authenticating and retrying`, 'warn');
+          await loginToWebsite(activePage, _loginCreds).catch(() => {});
+          await activePage.goto(url, { waitUntil: 'domcontentloaded', timeout: DEFAULT_NAV_TIMEOUT });
+          await activePage.waitForTimeout(800);
+
+          if (isSessionExpired(activePage.url())) {
+            // Still on login after fresh auth — this route needs a different role/permission
+            authGated = true;
+            logActivity('QA', `AUTH_REQUIRED: ${url} — needs elevated permissions`, 'warn');
+          }
+        }
+
+        if (authGated) {
+          report.warnings.push({
+            url,
+            warnings: [`Route requires elevated permissions (redirects to login even with valid session)`],
+            category: 'auth_required',
+          });
+          logActivity('QA', `SKIP: ${url} — auth-gated`, 'warn');
+          continue; // Don't count as pass or fail — it's not a bug
+        }
+
+        const { errors, warnings } = await checkPageHealth(activePage, url);
+
+        // V2: Respect readOnlyMode — skip interactive tests
+        if (!qaConfig.readOnlyMode) {
+          const interactiveIssues = await testInteractiveElements(activePage, url, maxActionsPerPage);
+          warnings.push(...interactiveIssues.filter(i => i.type === 'warning').map(i => i.message));
+        }
+
+        const shotPath = await store.capture(activePage, slugify(url));
+        report.screenshots.push(shotPath);
+
+        const hasRegression = await store.compareWithBaseline(shotPath, slugify(url));
+
+        if (errors.length > 0 || hasRegression) {
+          report.failed.push({
+            url,
+            errors,
+            warnings,
+            screenshot: shotPath,
+            visualRegression: hasRegression,
+            timestamp: new Date().toISOString(),
+          });
+          logActivity('QA', `FAIL: ${url} — ${errors.length} error(s)`, 'error');
+        } else {
+          report.passed.push({ url, warnings, screenshot: shotPath });
+          if (warnings.length > 0) {
+            report.warnings.push({ url, warnings });
+          }
+          logActivity('QA', `PASS: ${url}`, 'success');
+        }
+      } catch (err) {
+        // V2: Handle browser crash mid-crawl
+        if (err.message.includes('Target closed') || err.message.includes('browser has been closed')) {
+          logActivity('QA', 'Browser crashed — restarting', 'warn');
+          try {
+            await activeBrowser.close().catch(() => {});
+            activeBrowser = await chromium.launch({
+              headless: true,
+              args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-dev-shm-usage'],
+            });
+            activeContext = await activeBrowser.newContext({
+              viewport: { width: 1280, height: 800 },
+              userAgent: 'AICC-QA-Agent/1.0',
+            });
+            activePage = await activeContext.newPage();
+            if (qaConfig.credentials) {
+              await loginToWebsite(activePage, {
+                loginUrl: qaConfig.credentials.loginUrl || qaConfig.targetUrl + '/login',
+                email: qaConfig.credentials.email,
+                password: qaConfig.credentials.password,
+                loginSelectors: qaConfig.credentials.loginSelectors,
+              }).catch(() => {});
+            }
+            routesSinceBrowserRestart = 0;
+          } catch { /* can't recover */ }
+          continue; // Skip this route, continue with next
+        }
+
+        report.failed.push({
+          url,
+          errors: [`Navigation/test error: ${err.message.slice(0, 200)}`],
+          warnings: [],
+          screenshot: null,
+          timestamp: new Date().toISOString(),
+        });
+        logActivity('QA', `ERROR: ${url} — ${err.message.slice(0, 80)}`, 'error');
+      }
+    }
+
+    // ── 4. Summary ────────────────────────────────────────────────────────────
+    const authGatedCount = report.warnings.filter(w => w.category === 'auth_required').length;
+    const testedRoutes   = routes.length - authGatedCount; // Don't count auth-gated in pass rate
+
+    report.summary = {
+      totalRoutes:  routes.length,
+      testedRoutes,
+      passed:       report.passed.length,
+      failed:       report.failed.length,
+      authGated:    authGatedCount,
+      warningsOnly: report.warnings.filter(w => w.category !== 'auth_required').length,
+      passRate:     testedRoutes > 0
+        ? Math.round((report.passed.length / testedRoutes) * 100)
+        : 0,
+    };
+
+    const authNote = authGatedCount > 0 ? ` (${authGatedCount} auth-gated, skipped)` : '';
+    logActivity('QA', `QA complete: ${report.summary.passed}/${testedRoutes} tested passed${authNote}`, 'info');
+
+  } finally {
+    await browser.close().catch(() => {});
+  }
+
+  // ── 5. Write report ───────────────────────────────────────────────────────
+  const reportPath = resolve(qaReportDir, `QA-${timestamp}.json`);
+  writeFileSync(reportPath, JSON.stringify(report, null, 2));
+  logActivity('QA', `Report written: ${reportPath}`, 'info');
+
+  updateStatus({
+    qa_last_report: reportPath,
+    qa_last_run:    new Date().toISOString(),
+    qa_pass_rate:   report.summary.passRate,
+  });
+
+  return report;
+}
+
+/**
+ * Read the most recent QA report from disk.
+ */
+export function getLatestQAReport() {
+  const qaReportDir = resolve(getWorkflowDir(), 'qa-reports');
+  if (!existsSync(qaReportDir)) return null;
+
+  const files = readdirSync(qaReportDir)
+    .filter(f => f.startsWith('QA-') && f.endsWith('.json'))
+    .sort()
+    .reverse();
+
+  if (files.length === 0) return null;
+  return JSON.parse(readFileSync(resolve(qaReportDir, files[0]), 'utf8'));
+}