agentic-qe 3.9.8 → 3.9.10

package/.claude/skills/qe-browser/scripts/visual-diff.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+// qe-browser: visual regression against stored PNG baselines.
+//
+// Usage:
+//   node visual-diff.js --name homepage
+//   node visual-diff.js --name homepage --threshold 0.02
+//   node visual-diff.js --name hero --selector "#hero"      # not supported in v26.3.x
+//   node visual-diff.js --name homepage --update-baseline
+//
+// THRESHOLD SEMANTICS (M1 — devil's-advocate finding):
+//   --threshold is the MAX FRACTION of pixels allowed to differ before the
+//   check fails. The default is 0.10 (10% of pixels may differ).
+//     - threshold 0.00 → require pixel-perfect match
+//     - threshold 0.02 → allow up to 2% pixel difference
+//     - threshold 0.50 → allow up to 50% pixel difference (very lax)
+//   Internally we compute `similarity = 1 - diffPixels / totalPixels` and
+//   pass when `similarity >= 1 - threshold`. This is the standard convention
+//   used by Playwright's `maxDiffPixelRatio` and BackstopJS.
+//
+// Baselines live in .aqe/visual-baselines/<sanitized-name>.png
+// Diff images (if pixelmatch available) go to .aqe/visual-baselines/<name>.diff.png
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const {
+  vibium,
+  envelope,
+  parseArgs,
+  emit,
+  fail,
+  runOrSkip,
+  rethrowIfUnavailable,
+} = require('./lib/vibium');
+
+const BASELINE_DIR = path.join(process.cwd(), '.aqe', 'visual-baselines');
+
+function sanitize(name) {
+  return String(name).replace(/[^A-Za-z0-9_-]/g, '_');
+}
+
+function ensureDir(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}
+
+// Vibium screenshot quirks (verified against v26.3.18 on 2026-04-09):
+//   1. `vibium screenshot -o <path>` IGNORES the directory in <path>.
+//      Only the basename is used, and the file is saved to
+//      `~/Pictures/Vibium/<basename>`. We work around this by reading from
+//      Vibium's actual output dir and copying to the requested location.
+//   2. `--selector` flag does NOT exist on `vibium screenshot`. Selector-
+//      scoped baselines are not supported in v26.3.x. We surface a clear
+//      error if a caller passes one. Future Vibium versions may add it.
+function vibiumPicturesDir() {
+  // Vibium hardcodes ~/Pictures/Vibium as the screenshot output directory.
+  return path.join(process.env.HOME || '/home/vscode', 'Pictures', 'Vibium');
+}
+
+function captureScreenshot(selector, outputPath) {
+  if (selector) {
+    throw new Error(
+      'vibium screenshot --selector is not supported in Vibium v26.3.x. ' +
+      'Drop the --selector argument and crop the resulting full-page PNG with ' +
+      'a separate image-processing step (e.g. ImageMagick `convert -crop`). ' +
+      'Tracking upstream — if Vibium adds --selector support, this script ' +
+      'should switch to passing it through.'
+    );
+  }
+  const basename = path.basename(outputPath);
+  const args = ['screenshot', '-o', basename, '--full-page'];
+  const res = vibium(args);
+  if (res.status !== 0) {
+    throw new Error(`vibium screenshot failed: ${res.stderr.trim() || res.stdout.trim()}`);
+  }
+  // Vibium wrote the file to ~/Pictures/Vibium/<basename>, not outputPath.
+  // Copy it to where the caller asked. Use copy-then-unlink so we leave
+  // Vibium's own dir clean for the next run.
+  const vibiumPath = path.join(vibiumPicturesDir(), basename);
+  if (!fs.existsSync(vibiumPath)) {
+    throw new Error(`screenshot output not created at ${vibiumPath} (vibium said: ${res.stdout.trim()})`);
+  }
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.copyFileSync(vibiumPath, outputPath);
+  fs.unlinkSync(vibiumPath);
+  return outputPath;
+}
+
+function tryLoadPixelmatch() {
+  try {
+    const pixelmatch = require('pixelmatch');
+    const { PNG } = require('pngjs');
+    return { pixelmatch, PNG };
+  } catch (_err) {
+    return null;
+  }
+}
+
+function parsePngSize(buffer) {
+  // PNG header: 8 bytes signature + 8 bytes IHDR chunk length/type + 4 width + 4 height
+  if (buffer.length < 24) return null;
+  const sig = buffer.slice(0, 8);
+  const expected = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]);
+  if (!sig.equals(expected)) return null;
+  const width = buffer.readUInt32BE(16);
+  const height = buffer.readUInt32BE(20);
+  return { width, height };
+}
+
+function hashBuffer(buf) {
+  return crypto.createHash('sha256').update(buf).digest('hex');
+}
+
+function compareWithPixelmatch(baselineBuf, currentBuf, diffPath) {
+  const mod = tryLoadPixelmatch();
+  if (!mod) return null;
+  const { pixelmatch, PNG } = mod;
+  const baseline = PNG.sync.read(baselineBuf);
+  const current = PNG.sync.read(currentBuf);
+  if (baseline.width !== current.width || baseline.height !== current.height) {
+    return {
+      similarity: 0,
+      diffPixelCount: Math.max(
+        baseline.width * baseline.height,
+        current.width * current.height
+      ),
+      width: current.width,
+      height: current.height,
+      sizeMismatch: true,
+    };
+  }
+  const { width, height } = baseline;
+  const diff = new PNG({ width, height });
+  const diffCount = pixelmatch(baseline.data, current.data, diff.data, width, height, {
+    threshold: 0.1,
+  });
+  if (diffPath) {
+    fs.writeFileSync(diffPath, PNG.sync.write(diff));
+  }
+  const totalPixels = width * height;
+  return {
+    similarity: 1 - diffCount / totalPixels,
+    diffPixelCount: diffCount,
+    width,
+    height,
+    sizeMismatch: false,
+  };
+}
+
+function compareFallback(baselineBuf, currentBuf) {
+  // Exact-match fallback when pixelmatch is not installed.
+  // Same hash = identical; otherwise we only know width/height and rough similarity from byte diff.
+  const bSize = parsePngSize(baselineBuf);
+  const cSize = parsePngSize(currentBuf);
+  if (!bSize || !cSize) {
+    return {
+      similarity: 0,
+      diffPixelCount: 0,
+      width: cSize ? cSize.width : 0,
+      height: cSize ? cSize.height : 0,
+      sizeMismatch: true,
+      note: 'pixelmatch not installed and PNG header unreadable',
+    };
+  }
+  if (bSize.width !== cSize.width || bSize.height !== cSize.height) {
+    return {
+      similarity: 0,
+      diffPixelCount: 0,
+      width: cSize.width,
+      height: cSize.height,
+      sizeMismatch: true,
+      note: 'pixelmatch not installed; size mismatch',
+    };
+  }
+  const same = hashBuffer(baselineBuf) === hashBuffer(currentBuf);
+  return {
+    similarity: same ? 1 : 0,
+    diffPixelCount: same ? 0 : bSize.width * bSize.height,
+    width: cSize.width,
+    height: cSize.height,
+    sizeMismatch: false,
+    note: same ? undefined : 'pixelmatch not installed; exact-hash fallback reports 0 similarity',
+  };
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const name = args.name;
+  if (!name) return fail('visual-diff', 'missing --name argument');
+
+  const threshold = args.threshold !== undefined ? parseFloat(args.threshold) : 0.1;
+  if (Number.isNaN(threshold) || threshold < 0 || threshold > 1) {
+    return fail('visual-diff', '--threshold must be between 0 and 1');
+  }
+  const updateBaseline = Boolean(args['update-baseline']);
+  const selector = args.selector;
+
+  try {
+    ensureDir(BASELINE_DIR);
+    const sanitized = sanitize(name);
+    const baselinePath = path.join(BASELINE_DIR, `${sanitized}.png`);
+    const currentPath = path.join(BASELINE_DIR, `${sanitized}.current.png`);
+    const diffPath = path.join(BASELINE_DIR, `${sanitized}.diff.png`);
+
+    const startedAt = Date.now();
+    captureScreenshot(selector, currentPath);
+    const currentBuf = fs.readFileSync(currentPath);
+
+    if (!fs.existsSync(baselinePath) || updateBaseline) {
+      fs.writeFileSync(baselinePath, currentBuf);
+      const size = parsePngSize(currentBuf) || { width: 0, height: 0 };
+      return emit(
+        envelope({
+          operation: 'visual-diff',
+          summary: updateBaseline
+            ? `Baseline "${name}" updated`
+            : `Baseline "${name}" created`,
+          status: 'success',
+          details: {
+            visualDiff: {
+              name,
+              status: updateBaseline ? 'baseline_updated' : 'baseline_created',
+              similarity: 1,
+              diffPixelCount: 0,
+              width: size.width,
+              height: size.height,
+              threshold,
+              baselinePath,
+            },
+          },
+          metadata: { executionTimeMs: Date.now() - startedAt },
+        })
+      );
+    }
+
+    const baselineBuf = fs.readFileSync(baselinePath);
+    let cmp = compareWithPixelmatch(baselineBuf, currentBuf, diffPath);
+    if (cmp === null) cmp = compareFallback(baselineBuf, currentBuf);
+
+    const passed = cmp.similarity >= 1 - threshold && !cmp.sizeMismatch;
+    return emit(
+      envelope({
+        operation: 'visual-diff',
+        summary: passed
+          ? `Visual match for "${name}" (similarity ${cmp.similarity.toFixed(4)})`
+          : `Visual mismatch for "${name}" (similarity ${cmp.similarity.toFixed(4)} below threshold ${1 - threshold})`,
+        status: passed ? 'success' : 'failed',
+        details: {
+          visualDiff: {
+            name,
+            status: passed ? 'match' : 'mismatch',
+            similarity: cmp.similarity,
+            diffPixelCount: cmp.diffPixelCount,
+            width: cmp.width,
+            height: cmp.height,
+            threshold,
+            baselinePath,
+            diffPath: fs.existsSync(diffPath) ? diffPath : undefined,
+            note: cmp.note,
+          },
+        },
+        metadata: { executionTimeMs: Date.now() - startedAt },
+      })
+    );
+  } catch (err) {
+    rethrowIfUnavailable(err); // F1
+    return fail('visual-diff', err.message);
+  }
+}
+
+if (require.main === module) {
+  process.exit(runOrSkip('visual-diff', main));
+}
+
+module.exports = { compareWithPixelmatch, compareFallback, parsePngSize };

package/.claude/skills/qe-visual-accessibility/SKILL.md

@@ -61,9 +61,39 @@ Task("Audit accessibility", `
 `, "qe-accessibility-agent")
 ```
 
+## Browser engine
+
+All browser automation in this skill uses the **qe-browser** fleet skill (Vibium engine). See `.claude/skills/qe-browser/SKILL.md`. The `vibium` binary is installed by `aqe init`.
+
 ## Visual Testing Operations
 
-### 1. Visual Regression
+### 1. Visual Regression (via qe-browser)
+
+```bash
+# Establish baselines for the pages we care about
+for path in / /login /dashboard /settings; do
+  slug=$(echo "$path" | tr '/' '_' | sed 's/^_//' || echo root)
+  vibium go "https://production.example.com$path" && vibium wait load
+  node .claude/skills/qe-browser/scripts/visual-diff.js --name "baseline_${slug:-root}"
+done
+
+# Compare staging against those baselines
+for path in / /login /dashboard /settings; do
+  slug=$(echo "$path" | tr '/' '_' | sed 's/^_//' || echo root)
+  vibium go "https://staging.example.com$path" && vibium wait load
+  node .claude/skills/qe-browser/scripts/visual-diff.js \
+    --name "baseline_${slug:-root}" --threshold 0.001  # 0.1% pixel diff
+done
+```
+
+Ignore dynamic regions (timestamps, live counts) by scoping the diff to a selector that excludes them:
+
+```bash
+node .claude/skills/qe-browser/scripts/visual-diff.js \
+  --name hero --selector "main > .content"
+```
+
+Legacy programmatic TypeScript API (still available for tests that prefer it over shelling out):
 
 ```typescript
 await visualTester.compareScreenshots({

package/.claude/skills/security-visual-testing/SKILL.md

@@ -20,6 +20,24 @@ validation:
 
 # Security Visual Testing
 
+## Browser engine
+
+Uses the **qe-browser** fleet skill (`.claude/skills/qe-browser/`) for all browser automation. The Vibium engine (10MB Go binary, WebDriver BiDi) is installed automatically by `aqe init`. For security-visual workflows, qe-browser adds two things on top of stock visual testing: `check-injection.js` (scans page content for prompt-injection patterns before screenshots are stored) and `assert.js` (16 typed checks including `no_failed_requests` for detecting data-leak requests).
+
+```bash
+# Before storing any screenshot, scan the page
+vibium go "$TARGET_URL"
+vibium wait load
+node .claude/skills/qe-browser/scripts/check-injection.js --include-hidden
+INJ=$?
+if [ $INJ -ne 0 ]; then
+  echo "Prompt-injection findings — do NOT store screenshot"
+  exit $INJ
+fi
+# Safe to proceed with visual-diff
+node .claude/skills/qe-browser/scripts/visual-diff.js --name "${PAGE_NAME}"
+```
+
 <default_to_action>
 When performing security-aware visual testing:
 1. VALIDATE URLs before navigation (check for malicious patterns)

package/.claude/skills/skills-manifest.json

@@ -1,9 +1,9 @@
 {
-  "version": "1.3.0",
-  "generated": "2026-02-04T00:00:00.000Z",
-  "totalSkills": 48,
-  "totalQESkills": 80,
-  "description": "Agentic QE Fleet skills manifest - 48 Tier 3 verified QE skills. Total 80 QE skills on disk (48 Tier 3 + 32 additional including QCSD swarms, n8n testing, enterprise integration, pentest validation, qe-* domains).",
+  "version": "1.4.0",
+  "generated": "2026-04-09T00:00:00.000Z",
+  "totalSkills": 49,
+  "totalQESkills": 81,
+  "description": "Agentic QE Fleet skills manifest - 49 Tier 3 verified QE skills. Total 81 QE skills on disk (49 Tier 3 + 32 additional including QCSD swarms, n8n testing, enterprise integration, pentest validation, qe-* domains, qe-browser via ADR-091).",
   "categories": {
     "qcsd-phases": {
       "description": "QCSD (Quality Conscious Software Delivery) phase swarms for shift-left quality",
@@ -49,6 +49,13 @@
         "regression-testing"
       ]
     },
+    "browser-automation": {
+      "description": "Browser automation fleet skill using Vibium (WebDriver BiDi) with typed assertions, batch execution, visual diff, prompt-injection scanning, and semantic intents. Supersedes per-skill browser glue across a11y-ally, e2e-flow-verifier, visual-testing-advanced, and others. See ADR-091.",
+      "priority": "high",
+      "skills": [
+        "qe-browser"
+      ]
+    },
     "analysis-review": {
       "description": "Code and quality analysis skills",
       "priority": "medium",
@@ -905,7 +912,7 @@
   "optimizationTracking": {
     "targetReduction": "40-50%",
     "optimizedSkills": 7,
-    "totalSkills": 46,
+    "totalSkills": 47,
     "progress": "15.2%",
     "tokensSaved": 10200,
     "optimizedList": [
@@ -932,9 +939,9 @@
   },
   "metadata": {
     "generatedBy": "Agentic QE Fleet",
-    "fleetVersion": "3.9.8",
-    "manifestVersion": "1.3.0",
-    "lastUpdated": "2026-04-08T00:00:00.000Z",
+    "fleetVersion": "3.9.10",
+    "manifestVersion": "1.4.0",
+    "lastUpdated": "2026-04-13T00:00:00.000Z",
     "contributors": [
       {
         "name": "@fndlalit",
@@ -942,13 +949,13 @@
         "url": "https://github.com/fndlalit"
       }
     ],
-    "notes": "This manifest tracks 48 Tier 3 verified QE skills. Total 80 QE skills on disk (48 Tier 3 + 32 additional). Claude Flow platform skills (33) are managed separately.",
+    "notes": "This manifest tracks 49 Tier 3 verified QE skills. Total 81 QE skills on disk (49 Tier 3 + 32 additional). qe-browser added 2026-04-09 per ADR-091. Claude Flow platform skills (33) are managed separately.",
     "skillBreakdown": {
-      "qeSkillsTier3": 48,
+      "qeSkillsTier3": 49,
       "qeSkillsAdditional": 32,
-      "totalQESkills": 80,
+      "totalQESkills": 81,
       "platformSkills": 36,
-      "totalOnDisk": 113
+      "totalOnDisk": 114
     },
     "excludedCategories": {
       "reason": "Platform skills are available but not tracked in this QE-focused manifest",

package/.claude/skills/testability-scoring/SKILL.md

@@ -22,6 +22,29 @@ validation:
 
 # Testability Scoring
 
+## Browser engine
+
+Uses the **qe-browser** fleet skill (`.claude/skills/qe-browser/`) as the primary browser engine. Vibium is installed by `aqe init`. The legacy `scripts/run-assessment.sh` + Playwright path remains as a fallback when a team already has a Playwright test suite configured, but new runs should prefer:
+
+```bash
+vibium go "$TARGET_URL"
+vibium wait load
+vibium a11y-tree --json > /tmp/testability/tree.json
+vibium eval --stdin --json <<'EOF' > /tmp/testability/signals.json
+JSON.stringify({
+  headings: document.querySelectorAll('h1,h2,h3,h4,h5,h6').length,
+  testIds: document.querySelectorAll('[data-testid]').length,
+  forms: document.querySelectorAll('form').length,
+  ariaLabels: document.querySelectorAll('[aria-label]').length,
+  links: document.querySelectorAll('a[href]').length,
+});
+EOF
+node .claude/skills/qe-browser/scripts/assert.js --checks '[
+  {"kind": "no_console_errors"},
+  {"kind": "no_failed_requests"}
+]'
+```
+
 <default_to_action>
 When assessing testability:
 1. RUN assessment against target URL

package/.claude/skills/trust-tier-manifest.json

@@ -8,11 +8,11 @@
     "tier0": 51,
     "tier1": 5,
     "tier2": 7,
-    "tier3": 49,
-    "total": 112
+    "tier3": 50,
+    "total": 113
   },
   "validationStatus": {
-    "passing": 49,
+    "passing": 50,
     "failing": 0,
     "unknown": 12,
     "skipped": 51
@@ -294,6 +294,17 @@
         },
         "file": "qcsd-ideation-swarm/SKILL.md"
       },
+      {
+        "name": "qe-browser",
+        "category": "browser-automation",
+        "validation": {
+          "status": "passing",
+          "schemaPath": "schemas/output.json",
+          "validatorPath": "scripts/validate-config.json",
+          "evalPath": "evals/qe-browser.yaml"
+        },
+        "file": "qe-browser/SKILL.md"
+      },
       {
         "name": "qe-chaos-resilience",
         "validation": {

package/.claude/skills/visual-testing-advanced/SKILL.md

@@ -68,7 +68,47 @@ When detecting visual regressions or validating UI:
 
 ---
 
-## Visual Regression with Playwright
+## PRIMARY PATH: qe-browser visual-diff
+
+**Most visual regression work should go through the `qe-browser` fleet skill.** It wraps Vibium (WebDriver BiDi) and provides pixel-diff against stored baselines with threshold enforcement and diff-image output. See `.claude/skills/qe-browser/SKILL.md`.
+
+```bash
+# Navigate
+vibium go https://example.com
+vibium wait load
+
+# First run — creates baseline in .aqe/visual-baselines/homepage.png
+node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage
+
+# Subsequent runs — compare, non-zero exit on mismatch
+node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --threshold 0.02
+
+# Scope to a single region
+node .claude/skills/qe-browser/scripts/visual-diff.js --name hero --selector "#hero"
+
+# Responsive — run diff at each breakpoint
+for viewport in "375 667" "768 1024" "1920 1080"; do
+  read w h <<< "$viewport"
+  vibium viewport $w $h
+  node .claude/skills/qe-browser/scripts/visual-diff.js --name "homepage-${w}x${h}"
+done
+
+# Reset baseline after an intentional design change
+node .claude/skills/qe-browser/scripts/visual-diff.js --name homepage --update-baseline
+```
+
+Baselines live in `.aqe/visual-baselines/`. The script uses `pixelmatch` when installed, with a hash-based exact-match fallback otherwise. Non-zero exit when similarity < `1 - threshold`, so CI gating is `$?`-based.
+
+### When to keep Playwright visual regression
+
+Use the Playwright recipe below only when you need:
+- **AI semantic comparison** (Percy, Applitools) to ignore insignificant pixel drift
+- **Cross-browser rendering checks** in Firefox/WebKit (Vibium is Chrome-only today)
+- **Tight integration with an existing Playwright test suite**
+
+---
+
+## LEGACY: Visual Regression with Playwright (fallback)
 
 ```javascript
 import { test, expect } from '@playwright/test';

package/CHANGELOG.md

@@ -5,6 +5,81 @@ All notable changes to the Agentic QE project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.9.10] - 2026-04-13
+
+**Use any LLM provider for QE advisory tasks.** Route simple questions to cheaper models, keep complex reasoning on premium providers, and let the fleet automatically route around outages. Sensitive data is scrubbed before prompts leave your environment. ([ADR-092](docs/implementation/adrs/ADR-092-provider-agnostic-advisor-strategy.md))
+
+### Added
+
+- **Multi-provider advisor routing** — Distribute advisory tasks across Claude, OpenAI, Ollama, OpenRouter, or any compatible provider. Route by task complexity, cost, or provider health. If one provider goes down, the fleet routes around it automatically.
+- **Automatic PII redaction** — API keys, credentials, secrets, and PII are stripped from prompts before they reach any external advisor. Three modes: `strict` (credentials + PII), `balanced` (credentials only), `off` (for self-hosted like Ollama).
+- **Per-provider circuit breakers** — Detect provider degradation and stop sending requests before they time out. Automatic recovery probes re-enable providers when they come back.
+- **`aqe llm-router` CLI command** — Inspect provider health, circuit breaker state, routing weights, and configuration.
+- **8 QE agents upgraded** — coverage-specialist, fleet-commander, pentest-validator, queen-coordinator, risk-assessor, root-cause-analyzer, security-auditor, and test-architect all support multi-provider routing out of the box.
+
+### Fixed
+
+- Distribution pipeline edge cases when multiple providers respond simultaneously
+- Error handling in routing-feedback collection
+
+### Changed
+
+- Queen coordinator now delegates advisory tasks through the advisor routing layer
+- Tiny-dancer router gains an advisor fallback path for when primary routing is unavailable
+
+## [3.9.9] - 2026-04-09
+
+This release ships **`qe-browser`** — a new fleet skill that gives every QE agent a real browser through a ~10MB Go binary instead of a 300MB Playwright install. Built on [Vibium](https://github.com/VibiumDev/vibium) (WebDriver BiDi) and shipped under [ADR-091](docs/implementation/adrs/ADR-091-qe-browser-skill-vibium-engine.md).
+
+### Added
+
+- **`qe-browser` fleet skill** ([ADR-091](docs/implementation/adrs/ADR-091-qe-browser-skill-vibium-engine.md)) — Browser automation for QE agents with 5 helper scripts:
+  - `assert.js` — 16 typed assertion kinds (`url_contains`, `selector_visible`, `no_console_errors`, `element_count`, `title_matches`, etc.)
+  - `batch.js` — Multi-step execution with pre-validation, stop-on-failure, and delegation to `assert.js`
+  - `visual-diff.js` — Pixel-perfect baseline comparison with `pixelmatch`, hash fallback, configurable threshold
+  - `check-injection.js` — 14-pattern prompt-injection scanner ported from `gsd-browser` (MIT/Apache-2.0) with `--exclude-selector` for docs sites
+  - `intent-score.js` — 15 semantic intents (`submit_form`, `accept_cookies`, `fill_email`, `primary_cta`, etc.) ported from `gsd-browser`
+- **Vibium auto-install** — `aqe init` now installs the `vibium` CLI globally via npm during phase 09 with a pre-flight short-circuit when it's already on PATH (no banner on the common case).
+- **Typed missing-browser contract** — When vibium is not on PATH, helpers emit a structured `status: "skipped"` envelope with top-level `vibiumUnavailable: true`, `output.reason: "browser-engine-unavailable"`, and exit code **2** (distinct from 0=success and 1=failed). Downstream skills can branch on the flag instead of grepping error strings.
+- **Linux ARM64 workaround documentation** — Chromium symlink recipe for aarch64 Debian/codespace hosts where Google doesn't publish Chrome for Testing (verified against `chromium 146.0.7680.177-1~deb12u1`).
+- **7-gotcha migration guide** (`references/migration-from-playwright.md`) — Covers headless default, screenshot output directory quirk, absent `--selector` flag, `eval --stdin` last-expression contract, ARM64 install, viewport determinism, and first-install download time.
+- **End-to-end smoke test** (`scripts/smoke-test.sh`) — 10 test cases against pinned `httpbin.org` fixtures, including a tc011 that spawns helpers with a stripped `PATH` to verify the missing-vibium contract.
+- **103 unit tests** across 8 files covering assertion kinds, batch validation, check-injection patterns, intent-score whitelist, fixture server path traversal, and the missing-vibium end-to-end contract.
+
+### Fixed
+
+All fixes below are from a devil's-advocate review of the initial `qe-browser` implementation, captured in ADR-091 Phases 1 through 4:
+
+- **Assertion fail-closed on missing telemetry** — `runConsoleCheck`/`runNetworkCheck` used to fail-OPEN when the underlying `vibium console`/`vibium network` JSON was unavailable (silently reporting `no_console_errors: pass` when we couldn't tell). Now returns a typed `unavailable` sentinel that `runCheck` surfaces as `passed: false, unavailable: true`, per `feedback_no_unverified_failure_modes.md`.
+- **`intent-score.js` special-character corruption** — The script builder used `String.prototype.replace` with a raw substitution string, so scopes containing `$&`, `` $` ``, `$'`, or `$1-$9` corrupted the generated browser-side code. Switched to `split/join` for literal substitution.
+- **`visual-diff.js` unsupported `--selector`** — The `vibium screenshot --selector` flag does not exist in v26.3.x. Replaced the dead fallback path with an explicit error pointing at ImageMagick `convert -crop`.
+- **`vibium screenshot -o` directory ignored** — Vibium hardcodes `~/Pictures/Vibium/<basename>` regardless of the `-o` argument's directory. `visual-diff.js` now reads from Vibium's actual output path and copies to the caller's requested location.
+- **`vibium eval --stdin` return contract** — Vibium eval returns the LAST EXPRESSION value via `{"ok":true,"result":"<stringified>"}`, not `console.log` output. Added `unwrapEvalResult()` that parses the result string back, and removed `console.log` wrappers from all helper scripts.
+- **Headless container support** — Vibium defaults to "visible browser" and fails with `Missing X server or $DISPLAY` on headless containers. All helper scripts now auto-inject `--headless` into every `vibium` invocation (opt out via `QE_BROWSER_HEADED=1`).
+- **`parseArgs` `--key=value` form** — Previously only `--key value` (space-separated) was parsed. A user typing `--threshold=0.05` got `args["threshold=0.05"] = true` and the real `threshold` key stayed undefined. Now splits on the first `=` so both forms work and URL/base64 values containing `=` survive intact.
+- **`batch.js` no pre-validation** — A typo in step 17 used to surface AFTER steps 1-16 had executed with side effects. Added `validateAllSteps()` that walks every step's required fields before the first vibium call and aborts with a consolidated error listing all typos.
+- **`check-injection.js` ANSI escape passthrough** — Finding snippets included raw page text verbatim, so malicious pages could inject terminal control sequences that trigger on `cat findings.json`. Added `sanitizeSnippet()` that strips C0 controls (0x00-0x1F except `\t\n`) and DEL (0x7F).
+- **`check-injection.js` doc false positives** — Running the scanner on docs that talk about prompt injection self-flagged every heading. New `--exclude-selector "main, .docs-content"` strips subtrees from a cloned `<body>` before scanning; live page unchanged.
+- **`intent-score.js` bare-`x` false positives** — The `close_dialog` regex used a bare `/x/` that matched "fix", "exit", "extra", "sixteen". Anchored with `\bx\b`; Unicode `×` and `✕` unchanged.
+- **Fixture HTTP server bound to `0.0.0.0`** — Codespaces auto-forward 0.0.0.0 ports to the public preview URL, so running `fixtures/serve-skills.js` was silently exposing the skills tree. Default is now `127.0.0.1`; `QE_BROWSER_FIXTURE_HOST=0.0.0.0` is explicit opt-in.
+- **Fixture server path-traversal guard** — The `startsWith(SKILLS_ROOT)` check false-passes on sibling dirs that share a prefix and is fragile on Windows mixed separators. Replaced with `path.relative()` + `..` check (the canonical guard).
+- **`detectVibium` stderr-only semver** — `vibium --version` emits to stderr on some platforms. `detectVibium` now reads both stdout and stderr and extracts the semver with a regex that handles prerelease/build metadata.
+- **`installBrowserEngine` silent 1-3 minute freeze** — `spawnSync('npm install -g vibium')` blocks for 1-3 minutes on cold caches while Chrome for Testing downloads. Phase 09 now runs a pre-flight detect that short-circuits when vibium is already on PATH (no banner) and logs a "this can take 1-3 minutes on first run" message BEFORE the spawn on the cold path.
+- **`09-assets.ts` dead error catch** — The `installBrowserEngine` try/catch re-emitted raw errors with no recovery path. Wrapped with actionable guidance pointing at `npm install -g vibium` and a re-run of `aqe init`.
+
+### Changed
+
+- **`.gitignore`** — Added `.aqe/` for per-project qe-browser state (visual baselines and helper caches), with `!.aqe/visual-baselines/.gitkeep` carve-out so projects that opt in to committing baselines can do so by removing the ignore.
+- **11 skills migrated to reference `qe-browser`** — `a11y-ally`, `e2e-flow-verifier`, `qe-visual-accessibility`, `security-visual-testing`, `visual-testing-advanced`, `testability-scoring`, `compatibility-testing`, `accessibility-testing`, `localization-testing`, `observability-testing-patterns`, `enterprise-integration-testing`. Each SKILL.md now points at `.claude/skills/qe-browser/` instead of embedding Playwright snippets.
+- **Skill counts bumped across user-facing docs** — README headline `74 → 75`, Tier 3 `48 → 49`, `.claude/skills/README.md` total `84 → 85`, V3 Domain Skills `23 → 24`. `skills-manifest.json` bumped to manifest version `1.4.0` with a new `browser-automation` category, `fleetVersion: "3.9.9"`. `trust-tier-manifest.json` bumped `tier3: 49 → 50`, `total: 112 → 113`.
+
+### Verified
+
+- **Fresh `aqe init --auto`** in `/tmp/qe-browser-uat` against the local build — 85 skills / 60 agents installed, `Browser engine: vibium 26.3.18 (already installed)` logged cleanly.
+- **12 user-perspective checks** against the installed skill — navigate + assert on httpbin, `--threshold=0.42` form, `batch.js` pre-validation aborting on typos, `intent-score.js submit_form`, `check-injection.js --exclude-selector` (visibleChars 3595 → 35), fixture server banner (`127.0.0.1`), path traversal returns 404, missing-vibium fallback, installed `smoke-test.sh` 10/10, idempotent re-init, JSON envelope contract.
+- **Unit tests** — 103 tests across 8 files, all passing: `qe-browser-assert`, `qe-browser-batch`, `qe-browser-check-injection`, `qe-browser-intent-score`, `qe-browser-vibium-lib`, `qe-browser-fixtures-server`, `qe-browser-unavailable-e2e`, `browser-engine-installer`.
+- **Smoke test** — 10/10 against real Vibium v26.3.18 + Chromium 146.0.7680.177 + `httpbin.org` pinned fixtures.
+
 ## [3.9.8] - 2026-04-08
 
 This is a release-process release. **No source code changes** — every commit since v3.9.7 lands in CI, fixtures, scripts, or docs. The published package is functionally identical to v3.9.7 except for a refreshed lockfile with two transitive security patches.

package/README.md

@@ -159,24 +159,26 @@ Plus **7 TDD subagents** (red, green, refactor, code/integration/performance/sec
 
 ---
 
-## 74 QE Skills
+## 75 QE Skills
 
 Agents automatically apply relevant skills from the skill library. Skills are rated by **trust tier**:
 
 | Tier | Count | Meaning |
 |------|-------|---------|
-| **Tier 3 — Verified** | 48 | Full evaluation test suite, production-ready |
+| **Tier 3 — Verified** | 49 | Full evaluation test suite, production-ready |
 | **Tier 2 — Validated** | 7 | Has executable validator |
 | **Tier 1 — Structured** | 5 | Has JSON output schema |
 | **Tier 0 — Advisory** | 5 | Guidance only |
 
 <details>
-<summary><b>View all 74 skills</b></summary>
+<summary><b>View all 75 skills</b></summary>
 
 **Core Testing (12):** agentic-quality-engineering, holistic-testing-pact, context-driven-testing, tdd-london-chicago, xp-practices, risk-based-testing, test-automation-strategy, refactoring-patterns, shift-left-testing, shift-right-testing, regression-testing, verification-quality
 
 **Specialized Testing (13):** accessibility-testing, mobile-testing, database-testing, contract-testing, chaos-engineering-resilience, visual-testing-advanced, security-visual-testing, compliance-testing, compatibility-testing, localization-testing, mutation-testing, performance-testing, security-testing
 
+**Browser Automation (1):** qe-browser (Vibium engine — assert, batch, visual-diff, prompt-injection scanning, semantic intents; see [ADR-091](docs/implementation/adrs/ADR-091-qe-browser-skill-vibium-engine.md))
+
 **Domain Skills (11):** qe-test-generation, qe-test-execution, qe-coverage-analysis, qe-quality-assessment, qe-defect-intelligence, qe-requirements-validation, qe-code-intelligence, qe-visual-accessibility, qe-chaos-resilience, qe-learning-optimization, qe-iterative-loop
 
 **Strategic (8):** six-thinking-hats, brutal-honesty-review, sherlock-review, cicd-pipeline-qe-orchestrator, bug-reporting-excellence, consultancy-practices, quality-metrics, pair-programming