qaa-agent 1.7.0 → 1.7.3

package/README.md

@@ -0,0 +1,380 @@
+# QAA - QA Automation Agent
+
+[![npm version](https://img.shields.io/npm/v/qaa-agent.svg)](https://www.npmjs.com/package/qaa-agent)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+Multi-agent QA pipeline for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Analyzes any codebase, generates a complete test suite following industry standards, validates everything, and delivers the result as a draft pull request.
+
+```
+scan → map → analyze → plan → generate → validate → deliver
+```
+
+No manual test writing. No guessing what to cover. One command, full pipeline.
+
+---
+
+## The Problem
+
+- **Starting from zero is painful** — a new project with no tests means weeks of setup
+- **Coverage gaps are invisible** — without analysis, teams don't know what's missing until production breaks
+- **Standards drift** — different team members write tests differently: inconsistent locators, vague assertions, mixed naming
+- **QA is always behind dev** — features ship faster than tests get written
+
+## The Solution
+
+QAA runs a pipeline of 12 specialized AI agents, each responsible for one stage:
+
+| Stage | What happens | Output |
+|-------|-------------|--------|
+| **Scan** | Detects framework, language, testable surfaces | `SCAN_MANIFEST.md` |
+| **Map** | Deep-scans codebase with 4 parallel agents (testability, risk, patterns, existing tests) | 8 codebase documents |
+| **Analyze** | Produces risk assessment, test inventory, testing pyramid | `QA_ANALYSIS.md`, `TEST_INVENTORY.md` |
+| **Plan** | Groups test cases by feature, assigns to files, resolves dependencies | `GENERATION_PLAN.md` |
+| **Generate** | Writes test files, POMs, fixtures, configs following project standards | Test suite on disk |
+| **Validate** | 4-layer validation (syntax, structure, dependencies, logic) with auto-fix | `VALIDATION_REPORT.md` |
+| **Deliver** | Creates branch, commits per stage, opens draft PR | Pull request URL |
+
+---
+
+## Install
+
+```bash
+npx qaa-agent
+```
+
+The interactive installer:
+
+1. Copies agents, commands, skills, templates, and workflows into your runtime directory
+2. Configures the [Playwright MCP](https://github.com/anthropics/mcp-playwright) server in your user-scope config (`~/.claude.json`) so it's available in **all projects**
+3. Merges required permissions into `settings.json`
+
+**Supported runtimes:** Claude Code, OpenCode
+
+**Install scope:** Global (`~/.claude/`, available in all projects) or Local (`./.claude/`, this project only)
+
+### Requirements
+
+- [Node.js](https://nodejs.org/) 18+
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed
+
+### Playwright MCP (required for E2E)
+
+QAA uses [`@playwright/mcp`](https://www.npmjs.com/package/@playwright/mcp) to open a real browser, extract locators from live pages, run E2E tests, and auto-fix locator mismatches.
+
+**You need to install the Playwright MCP server manually in your environment:**
+
+<details>
+<summary><strong>VS Code (Claude Code extension)</strong></summary>
+
+1. Open VS Code Settings (`Ctrl+Shift+P` > `Preferences: Open User Settings (JSON)`)
+2. Add the MCP server config:
+
+```json
+{
+  "claude-code.mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Or add it to your project's `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Code CLI</strong></summary>
+
+Add to `~/.claude.json` (user-scope, all projects):
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}
+```
+
+Or add a `.mcp.json` file in your project root for project-scope only.
+
+</details>
+
+Once configured, Playwright MCP enables QAA to:
+- Open a real browser and navigate your running app
+- Extract actual locators (`data-testid`, ARIA roles, labels) from live pages
+- Run E2E tests, capture failures, and auto-fix locator mismatches
+- Build a persistent **Locator Registry** (`.qa-output/locators/`) that caches real locators across features
+
+---
+
+## Quick Start
+
+### New project, no tests
+
+```
+/qa-start --dev-repo ./myproject --auto
+```
+
+Runs the full pipeline end-to-end: scan, map, analyze, plan, generate, validate, and deliver as a draft PR.
+
+### Mature project, new feature
+
+```
+/qa-map                                          # build the "brain" (once)
+/qa-create-test "password reset"                 # generate tests using codebase knowledge
+/qa-pr --ticket PROJ-123 "password reset tests"  # ship as draft PR
+```
+
+### From a Jira ticket
+
+```
+/qa-from-ticket https://company.atlassian.net/browse/PROJ-456
+/qa-pr --ticket PROJ-456 "login flow tests"
+```
+
+### Fix broken tests after a deploy
+
+```
+/qa-fix ./tests/e2e/checkout*
+/qa-pr --ticket PROJ-789 "fix checkout tests"
+```
+
+---
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/qa-start` | Full pipeline end-to-end (scan through PR) |
+| `/qa-map` | Deep codebase analysis with 4 parallel agents |
+| `/qa-create-test <feature>` | Generate tests for a specific feature |
+| `/qa-fix [path]` | Diagnose and fix broken tests |
+| `/qa-audit [path]` | 6-dimension quality audit with scoring |
+| `/qa-pr` | Create a draft pull request from QA artifacts |
+| `/qa-testid [path]` | Inject `data-testid` attributes into components |
+
+### Additional Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/qa-from-ticket <url>` | Generate tests from a Jira/Linear/GitHub Issue |
+| `/qa-analyze` | Analyze a repo without generating tests |
+| `/qa-validate [path]` | Validate test files against standards |
+| `/qa-gap` | Find coverage gaps between dev and QA repos |
+| `/qa-report` | Generate a QA status report |
+| `/qa-audit` | Full quality audit with weighted scoring |
+| `/qa-blueprint` | Generate QA repo structure from scratch |
+| `/qa-research` | Research best testing stack for a project |
+| `/qa-pom` | Generate Page Object Models |
+| `/update-test` | Improve existing tests incrementally |
+
+See [COMMANDS.md](docs/COMMANDS.md) for full usage details and flags.
+
+---
+
+## Three Workflows
+
+QAA adapts to the project's QA maturity:
+
+**Option 1: No QA repo yet** — Full pipeline from scratch. Produces a complete test suite, repo blueprint, and draft PR.
+
+```
+/qa-start --dev-repo ./myproject
+```
+
+**Option 2: Immature QA repo** — Scans both repos, fixes broken tests, fills coverage gaps, standardizes existing tests.
+
+```
+/qa-start --dev-repo ./myproject --qa-repo ./tests
+```
+
+**Option 3: Mature QA repo** — Surgical additions only. Finds thin coverage areas and adds targeted tests without touching working code.
+
+```
+/qa-start --dev-repo ./myproject --qa-repo ./tests
+```
+
+---
+
+## The "Brain" — Codebase Map
+
+Before generating anything, QAA maps the codebase with 4 parallel agents producing 8 documents:
+
+| Focus | Documents |
+|-------|-----------|
+| **Testability** | `TESTABILITY.md`, `TEST_SURFACE.md` — what's testable, entry points, mock boundaries |
+| **Risk** | `RISK_MAP.md`, `CRITICAL_PATHS.md` — business-critical paths, security-sensitive areas |
+| **Patterns** | `CODE_PATTERNS.md`, `API_CONTRACTS.md` — naming conventions, API shapes, import style |
+| **Existing tests** | `TEST_ASSESSMENT.md`, `COVERAGE_GAPS.md` — current quality, frameworks, gaps |
+
+Every downstream agent reads these documents. The result: generated tests feel native to the codebase, not generic boilerplate.
+
+---
+
+## Standards Enforced
+
+Every generated artifact follows strict rules defined in [CLAUDE.md](CLAUDE.md):
+
+### Testing Pyramid
+
+```
+         /  E2E  \        3-5%   (critical path smoke only)
+        /  API    \       20-25% (endpoints + contracts)
+       / Integration\     10-15% (component interactions)
+      /    Unit      \    60-70% (business logic, pure functions)
+```
+
+### Locator Hierarchy
+
+1. **Tier 1 (Best):** `data-testid`, ARIA roles with accessible names
+2. **Tier 2 (Good):** Form labels, placeholders, visible text
+3. **Tier 3 (Acceptable):** Alt text, title attributes
+4. **Tier 4 (Last Resort):** CSS selectors, XPath — always with a `// TODO` comment
+
+### Page Object Model
+
+- One class per page, no god objects
+- No assertions in POMs — assertions belong in test specs
+- Locators as readonly properties
+- Every POM extends a shared `BasePage`
+
+### Assertion Quality
+
+```typescript
+// Good — concrete values
+expect(response.status).toBe(200);
+expect(data.name).toBe('Test User');
+
+// Bad — never do this
+expect(response.status).toBeTruthy();
+expect(data).toBeDefined();
+```
+
+### Test Case IDs
+
+Every test case has a unique ID following the pattern:
+- `UT-MODULE-001` — unit tests
+- `INT-MODULE-001` — integration tests
+- `API-RESOURCE-001` — API tests
+- `E2E-FLOW-001` — E2E tests
+
+---
+
+## Validation
+
+Generated tests pass through a 4-layer validation with auto-fix (up to 3 loops):
+
+1. **Syntax** — does it parse? Are imports correct?
+2. **Structure** — POM rules, file organization, naming conventions
+3. **Dependencies** — all imports resolve, mocks set up correctly
+4. **Logic** — assertions are concrete, locators follow tier hierarchy
+
+If issues remain, the **Bug Detective** classifies each failure:
+
+| Classification | Action |
+|----------------|--------|
+| `APPLICATION BUG` | Flagged for developer — not auto-fixed |
+| `TEST CODE ERROR` | Auto-fixed at HIGH confidence |
+| `ENVIRONMENT ISSUE` | Documented with setup instructions |
+| `INCONCLUSIVE` | Flagged with evidence for manual review |
+
+---
+
+## Framework Support
+
+QAA auto-detects the project's existing stack and matches it:
+
+**Languages:** JavaScript/TypeScript, Python, Java, .NET/C#, Go, Ruby, PHP, Rust
+
+**Test Frameworks:** Playwright, Cypress, Jest, Vitest, pytest, Selenium, and more
+
+**Build Tools:** Vite, Next.js, Nuxt, Angular, Vue, Webpack, SvelteKit
+
+**Git Platforms:** GitHub, Azure DevOps, GitLab
+
+---
+
+## Learning System
+
+QAA remembers your preferences across sessions. When you correct it — "use Playwright, not Cypress" or "our branches start with `feature/`" — it saves the rule permanently to `MY_PREFERENCES.md`. Every agent reads your preferences before generating output.
+
+Your team's conventions always win over defaults.
+
+---
+
+## Architecture
+
+```
+qaa-agent/
+  agents/          # 12 specialized QA agents
+  commands/        # 7 slash commands (user-facing entry points)
+  skills/          # 6 reusable skills
+  templates/       # 10 artifact templates (output format contracts)
+  workflows/       # 7 workflow orchestration specs
+  bin/             # Installer and CLI tools
+  docs/            # User documentation
+  CLAUDE.md        # QA standards (read by every agent)
+  .mcp.json        # Playwright MCP server config
+  settings.json    # Claude Code permissions
+```
+
+### Agents
+
+| Agent | Responsibility |
+|-------|---------------|
+| `qa-scanner` | Framework detection, file tree scanning |
+| `qa-codebase-mapper` | 4-parallel-agent deep analysis |
+| `qa-analyzer` | Risk assessment, test inventory, pyramid |
+| `qa-planner` | Test case grouping, file assignment |
+| `qa-executor` | Test file, POM, fixture generation |
+| `qa-validator` | 4-layer validation with auto-fix |
+| `qa-e2e-runner` | Browser-based test execution via Playwright MCP |
+| `qa-bug-detective` | Failure classification with evidence |
+| `qa-testid-injector` | `data-testid` attribute injection |
+| `qa-project-researcher` | Testing stack research |
+| `qa-discovery` | Project discovery |
+| `qa-pipeline-orchestrator` | Pipeline coordination |
+
+---
+
+## Git Workflow
+
+QAA follows strict git conventions:
+
+- **Branch:** `qa/auto-{project}-{date}` (e.g., `qa/auto-shopflow-2026-03-18`)
+- **Commits:** One per agent stage — `qa(scanner): produce SCAN_MANIFEST.md for shopflow`
+- **PR:** Draft PR with analysis summary, test counts, coverage metrics, validation status
+
+---
+
+## Documentation
+
+- [Commands Reference](docs/COMMANDS.md) — all commands with flags and examples
+- [Demo & Walkthrough](docs/DEMO.md) — problem/solution explanation with real workflows
+- [Changelog](CHANGELOG.md) — version history
+
+---
+
+## License
+
+[MIT](LICENSE)
+
+---
+
+Built by [Capmation](https://github.com/capmation)

package/bin/install.cjs

@@ -146,9 +146,21 @@ async function main() {
   // Install .mcp.json (Playwright MCP server config)
   const mcpSrc = path.join(ROOT, '.mcp.json');
   if (fs.existsSync(mcpSrc)) {
-    const mcpDest = path.join(qaaDir, '.mcp.json');
-    copyFile(mcpSrc, mcpDest);
-    ok('Installed Playwright MCP server config (.mcp.json)');
+    // Copy to qaa dir for reference
+    copyFile(mcpSrc, path.join(qaaDir, '.mcp.json'));
+
+    // Merge MCP servers into ~/.claude.json (user-scope) so they're available in ALL projects
+    // Note: ~/.claude/.mcp.json is project-scope for ~/.claude/ only — NOT global
+    const userConfigPath = path.join(HOME, '.claude.json');
+    let userConfig = {};
+    if (fs.existsSync(userConfigPath)) {
+      try { userConfig = JSON.parse(fs.readFileSync(userConfigPath, 'utf8')); } catch {}
+    }
+    userConfig.mcpServers = userConfig.mcpServers || {};
+    const qaaMcp = JSON.parse(fs.readFileSync(mcpSrc, 'utf8'));
+    Object.assign(userConfig.mcpServers, qaaMcp.mcpServers);
+    fs.writeFileSync(userConfigPath, JSON.stringify(userConfig, null, 2));
+    ok('Installed Playwright MCP server config (user-scope — available in all projects)');
   }
 
   // Write version

package/commands/qa-fix.md

@@ -5,12 +5,13 @@ Validate, diagnose, and fix test files — all in one command. Runs 4-layer stat
 ## Usage
 
 ```
-/qa-fix [<test-directory>] [options]
+/qa-fix [<test-files-or-directory>] [options]
 ```
 
 ### Options
 
-- `<test-directory>` — path to test files (auto-detects if omitted)
+- `<test-files-or-directory>` — one or more test file paths or a directory (auto-detects if omitted)
+- `--check` — **final check mode**: full quality verification against company preferences, codebase conventions, and execution
 - `--validate-only` — run 4-layer static validation only, no test execution or classification
 - `--classify` — run tests and classify failures, but do NOT auto-fix
 - `--run --app-url <url>` — also execute E2E tests against live app after static validation
@@ -20,7 +21,9 @@ Validate, diagnose, and fix test files — all in one command. Runs 4-layer stat
 ### Mode Detection
 
 ```
-if --validate-only:
+if --check:
+  MODE = "check"           → full quality check + execution + QA_CHECK_REPORT.md
+elif --validate-only:
   MODE = "validate"        → 4-layer static validation + VALIDATION_REPORT.md
 elif --classify:
   MODE = "classify"        → run tests + classify failures (no auto-fix)
@@ -32,6 +35,8 @@ else:
 
 | Mode | Artifacts |
 |------|-----------|
+| check | QA_CHECK_REPORT.md (full quality verification with pass/fail per test file) |
+| check --ticket | QA_CHECK_REPORT.md + UAT_VERIFICATION.md (step-by-step screenshots vs ticket acceptance criteria) |
 | validate | VALIDATION_REPORT.md (syntax, structure, dependencies, logic per file) |
 | classify | FAILURE_CLASSIFICATION_REPORT.md (per-failure evidence, no fixes) |
 | fix | FAILURE_CLASSIFICATION_REPORT.md + auto-fixed test files |
@@ -57,6 +62,249 @@ App URL: {url or "auto-detect"}
 
 ---
 
+### CHECK MODE (`--check`) — Final Quality Verification
+
+Full quality check for specific test files. Reads ALL context sources, verifies every aspect of the tests, runs them, and produces a pass/fail report. Use this as a final gate before delivering tests.
+
+**Accepts specific files:**
+```
+/qa-fix --check tests/e2e/login.e2e.spec.ts tests/e2e/checkout.e2e.spec.ts
+/qa-fix --check tests/unit/auth.unit.spec.ts
+/qa-fix --check tests/e2e/ --app-url http://localhost:3000
+```
+
+**Step 1: Read ALL context sources**
+
+Read every available context source — this is not optional, all must be read:
+
+1. **CLAUDE.md** — QA standards, POM rules, locator tiers, assertion rules, naming conventions, quality gates
+2. **~/.claude/qaa/MY_PREFERENCES.md** — company/user preferences that OVERRIDE CLAUDE.md rules
+3. **Codebase map** (`.qa-output/codebase/`):
+   - `CODE_PATTERNS.md` — naming conventions, import style, file organization (are tests matching the project's style?)
+   - `API_CONTRACTS.md` — real API shapes (are API test payloads correct?)
+   - `TEST_SURFACE.md` — function signatures (are test targets real?)
+   - `TESTABILITY.md` — mock boundaries (are mocks set up correctly?)
+4. **Locator Registry** (`.qa-output/locators/`) — real locators from the app (are POM locators accurate?)
+5. **Existing test patterns** — read 2-3 existing test files in the same repo to understand current conventions (describe block style, import patterns, assertion patterns, fixture usage)
+
+If codebase map is missing, STOP and tell the user to run `/qa-map` first.
+
+**Step 2: Verify each test file across 7 dimensions**
+
+For EACH selected test file, check:
+
+| # | Dimension | What to check | Source |
+|---|-----------|---------------|--------|
+| 1 | **Naming** | File name, test IDs, describe/it names follow conventions | CLAUDE.md + CODE_PATTERNS.md + MY_PREFERENCES.md |
+| 2 | **Structure** | Correct directory, imports resolve, follows repo patterns | CODE_PATTERNS.md + existing tests in repo |
+| 3 | **Locators** | POM locators match registry, Tier 1 preferred, no stale selectors | LOCATOR_REGISTRY.md |
+| 4 | **Assertions** | Concrete values (no toBeTruthy alone), match API contracts | CLAUDE.md + API_CONTRACTS.md |
+| 5 | **POM compliance** | No assertions in POMs, locators as properties, extends BasePage | CLAUDE.md |
+| 6 | **Code quality** | No redundant code, no dead code, no hardcoded credentials, no copy-paste | Code review |
+| 7 | **Company conventions** | Matches all rules in MY_PREFERENCES.md | MY_PREFERENCES.md |
+
+**Step 3: Run the tests**
+
+Execute the selected test files:
+
+```bash
+# Detect test runner from project config
+npx playwright test {files} --reporter=json 2>&1    # if Playwright
+npx cypress run --spec {files} 2>&1                  # if Cypress
+npx jest {files} --json 2>&1                         # if Jest
+npx vitest run {files} --reporter=json 2>&1          # if Vitest
+```
+
+If E2E tests and app URL available, also verify with Playwright MCP:
+- Navigate to each page referenced in the tests
+- `browser_snapshot()` to verify elements exist in DOM
+- Cross-reference locators against real page
+
+**Step 4: Fix issues found**
+
+For each issue found:
+- **AUTO-FIX** (HIGH confidence): naming, imports, locator mismatches, missing await, Tier 4→Tier 1 upgrade when registry has the value
+- **FLAG for review** (MEDIUM/LOW): logic changes, assertion value changes, structural refactors
+- Re-run tests after fixes (max 5 loops)
+
+**Step 5: Produce QA_CHECK_REPORT.md**
+
+```markdown
+# QA Check Report
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Files checked | {N} |
+| Dimensions checked | 7 |
+| Issues found | {N} |
+| Auto-fixed | {N} |
+| Flagged for review | {N} |
+| Tests passed | {N}/{total} |
+| Overall | PASS / PASS WITH WARNINGS / FAIL |
+
+## Per-File Results
+
+### {file_path}
+
+| Dimension | Status | Details |
+|-----------|--------|---------|
+| Naming | PASS/FAIL | {specific details} |
+| Structure | PASS/FAIL | {specific details} |
+| Locators | PASS/FAIL | {specific details} |
+| Assertions | PASS/FAIL | {specific details} |
+| POM compliance | PASS/FAIL | {specific details} |
+| Code quality | PASS/FAIL | {specific details} |
+| Company conventions | PASS/FAIL | {specific details} |
+
+**Test execution:** PASS / FAIL ({error if failed})
+**Fixes applied:** {list of auto-fixes}
+**Flagged for review:** {list of items needing human review}
+
+[... repeat per file ...]
+
+## Flagged Items (Needs Human Review)
+
+| File | Dimension | Issue | Suggested Fix |
+|------|-----------|-------|---------------|
+| ... | ... | ... | ... |
+```
+
+Write to `.qa-output/QA_CHECK_REPORT.md`.
+
+Present results to user with clear PASS/FAIL per file and overall status.
+
+**Step 6 (optional): Ticket Verification (`--ticket <source>`)**
+
+If `--ticket` flag is provided, perform UAT verification — walk through the test flow step-by-step in the browser, take screenshots at each step, and compare against the ticket's acceptance criteria.
+
+**Usage:**
+```
+/qa-fix --check --ticket #123 tests/e2e/login.e2e.spec.ts --app-url http://localhost:3000
+/qa-fix --check --ticket https://company.atlassian.net/browse/PROJ-456 tests/e2e/checkout.e2e.spec.ts
+/qa-fix --check --ticket "User logs in, sees dashboard with welcome message, clicks profile" tests/e2e/login.e2e.spec.ts
+```
+
+**Requires:** `--app-url` or auto-detected running app. Cannot do ticket verification without a live app.
+
+**Step 6a: Fetch and parse the ticket**
+
+Same ticket parsing as `/qa-create-test` from-ticket mode:
+- GitHub Issue: `gh issue view` → extract title, body, ACs
+- Jira/Linear URL: `WebFetch` → extract content
+- Plain text: use directly as acceptance criteria
+- File path: read file content
+
+Extract:
+- Acceptance criteria (AC-1, AC-2, ...)
+- Expected user flow (step-by-step)
+- Expected outcomes per step
+
+**Step 6b: Walk through the flow with Playwright MCP**
+
+For each E2E test file being checked, replay the user journey manually in the browser step-by-step:
+
+```
+For each step in the ticket's user flow:
+
+  1. Execute the action described in the step:
+     - Navigate: mcp__playwright__browser_navigate({ url: "{page}" })
+     - Fill form: mcp__playwright__browser_fill_form({ ... })
+     - Click: mcp__playwright__browser_click({ element: "..." })
+     - Wait: mcp__playwright__browser_wait_for({ text: "..." })
+
+  2. Take screenshot AFTER the action:
+     mcp__playwright__browser_take_screenshot()
+     → Save to .qa-output/uat-screenshots/{test-name}-step-{N}.png
+
+  3. Take accessibility snapshot to read page state:
+     mcp__playwright__browser_snapshot()
+
+  4. Record what the page shows:
+     - URL after action
+     - Visible text/headings
+     - Form state
+     - Error messages (if any)
+     - Elements visible/hidden
+```
+
+**Step 6c: Compare actual vs ticket**
+
+For each acceptance criterion from the ticket:
+
+| AC | Expected (from ticket) | Actual (from browser) | Screenshot | Verdict |
+|----|----------------------|---------------------|------------|---------|
+| AC-1 | User sees login form | Login form visible with email/password fields | step-1.png | MATCH |
+| AC-2 | After login, redirect to dashboard | Redirected to /dashboard, "Welcome" visible | step-3.png | MATCH |
+| AC-3 | Error message for wrong password | "Invalid credentials" alert shown | step-5.png | MATCH |
+| AC-4 | Remember me keeps session | Session persists after browser close | step-7.png | MISMATCH — session expired |
+
+Verdicts:
+- **MATCH** — actual behavior matches what the ticket describes
+- **MISMATCH** — actual behavior differs from ticket (could be app bug OR test not covering this AC)
+- **NOT TESTED** — ticket has an AC but no test step covers it
+- **EXTRA** — test covers something not in the ticket (informational, not a failure)
+
+**Step 6d: Produce UAT_VERIFICATION.md**
+
+```markdown
+# UAT Verification Report
+
+## Ticket Info
+
+| Field | Value |
+|-------|-------|
+| Source | {ticket URL or text} |
+| Title | {ticket title} |
+| ACs extracted | {count} |
+| Test files verified | {count} |
+
+## Step-by-Step Walkthrough
+
+### Step 1: {action description}
+- **Action:** Navigate to /login
+- **Screenshot:** [step-1.png](.qa-output/uat-screenshots/{test}-step-1.png)
+- **Page state:** Login form visible, email and password fields empty, "Log in" button enabled
+- **Matches AC:** AC-1 ✓
+
+### Step 2: {action description}
+- **Action:** Fill email "test@example.com", password "SecureP@ss123!"
+- **Screenshot:** [step-2.png]
+- **Page state:** Fields filled, button still enabled
+- **Matches AC:** (intermediate step, no AC)
+
+[... repeat per step ...]
+
+## AC Coverage Matrix
+
+| AC | Description | Tested | Verdict | Evidence |
+|----|-------------|--------|---------|----------|
+| AC-1 | Login form visible | Yes | MATCH | step-1.png |
+| AC-2 | Redirect to dashboard | Yes | MATCH | step-3.png |
+| AC-3 | Error on wrong password | Yes | MATCH | step-5.png |
+| AC-4 | Remember me session | No | NOT TESTED | — |
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| ACs from ticket | {N} |
+| ACs matched | {N} |
+| ACs mismatched | {N} |
+| ACs not tested | {N} |
+| Screenshots captured | {N} |
+| Overall | PASS / PARTIAL / FAIL |
+```
+
+Write to `.qa-output/UAT_VERIFICATION.md`.
+
+If any AC is MISMATCH or NOT TESTED, present to user with recommendation:
+- MISMATCH → "AC-4 says X but the app does Y — either the app has a bug or the test needs updating"
+- NOT TESTED → "AC-4 is not covered by any test step — consider adding a test case"
+
+---
+
 ### VALIDATE MODE (`--validate-only`)
 
 1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.7.0",
+  "version": "1.7.3",
   "description": "QA Automation Agent for Claude Code — multi-agent pipeline that analyzes repos, generates tests, validates, and creates PRs",
   "bin": {
     "qaa-agent": "./bin/install.cjs"