qaa-agent 1.8.6 → 1.9.0

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 
 All notable changes to QAA (QA Automation Agent) are documented here.
 
+## [1.9.0] - 2026-04-24
+
+### Added
+
+- **`/qa-research` command** — new standalone command that invokes the `qaa-project-researcher` agent to investigate the testing ecosystem for the current project. Supports 4 modes via `--focus` flag: `stack-testing` (default, full stack analysis), `framework-deep-dive` (deep dive into detected framework), `api-testing` (API testing strategy), `e2e-strategy` (E2E strategy). Produces research documents in `.qa-output/research/` consumed by all downstream agents.
+- **Research stage in `/qa-start` pipeline** — the full pipeline now runs `scan → research → codebase-map → analyze → ...`. The researcher agent runs after the scanner, using Context7 MCP as the primary source for framework documentation. Research is non-blocking: if it fails, downstream agents fall back to querying Context7 directly.
+- **Context7 MCP mandatory in 3 agents** — `qaa-executor`, `qaa-e2e-runner`, and `qaa-bug-detective` now have a non-negotiable "Framework Verification via Context7" section. Before generating code, fixing locators, or auto-fixing test errors, these agents MUST query Context7 for the framework's current API and syntax. This applies to ALL frameworks including well-known ones (Playwright, Cypress, Jest) — training data may be outdated.
+- **Research documents propagated across commands** — `/qa-create-test`, `/qa-fix`, and `/qa-start` now pass research documents (`FRAMEWORK_CAPABILITIES.md`, `TESTING_STACK.md`, `E2E_STRATEGY.md`, `API_TESTING_STRATEGY.md`) to executor, e2e-runner, and bug-detective agents via `files_to_read`. Documents are optional — if they don't exist, agents query Context7 directly.
+- **Context7 verification in quality gate checklists** — executor, e2e-runner, and bug-detective now include Context7-specific items in their verification checklists (e.g., "Context7 was queried for selector API before generating POM files").
+
+### Changed
+
+- **`qaa-project-researcher` agent updated** — Context7 MCP tools (`resolve-library-id`, `query-docs`) now declared explicitly in frontmatter. Output path changed from `specs/research/` to `.qa-output/research/`. Added version awareness section: detects project's current framework version, generates all syntax for that version, and includes an informational note about newer versions (without recommending upgrade).
+- **Pipeline diagram updated** — all pipeline references across CLAUDE.md, README.md, and workflows now include the `research` stage: `scan → research → codebase-map → analyze → ...`.
+- **Module boundaries and dependency ordering updated** — CLAUDE.md now includes `qa-project-researcher` in the module boundaries table, stage transitions table, dependency ordering, and read-before-write rules.
+
+### Fixed
+
+- **`qaa-project-researcher` was an orphaned agent** — the agent existed since v1.2.0 but was never invoked by any command, workflow, or the pipeline orchestrator. The `/qa-research` command documented in `docs/COMMANDS.md` never had a corresponding file in `/commands/`. No downstream agent read its output files. This release connects the researcher to the pipeline and creates the missing command.
+
 ## [1.8.6] - 2026-04-20
 
 ### Added

package/CLAUDE.md

@@ -197,7 +197,7 @@ The QA automation system runs agents in a defined pipeline. Each stage produces
 ### Pipeline Stages
 
 ```
-scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
+scan -> research -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
 ```
 
 ### Workflow Options
@@ -205,7 +205,7 @@ scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> genera
 **Option 1: Dev-Only Repo (no existing QA repo)**
 Full pipeline from scratch:
 ```
-scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
+scan -> research -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
 ```
 Produces: SCAN_MANIFEST.md -> 8 codebase map documents -> QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md -> [TESTID_AUDIT_REPORT.md] -> generation plan -> test files + POMs + fixtures + configs -> VALIDATION_REPORT.md -> [E2E_RUN_REPORT.md] -> branch + PR
 
@@ -227,7 +227,8 @@ Produces: SCAN_MANIFEST.md (both repos) -> GAP_ANALYSIS.md (thin areas only) ->
 
 | From | To | Condition |
 |------|----|-----------|
-| scan | codebase-map | SCAN_MANIFEST.md exists with > 0 testable surfaces |
+| scan | research | SCAN_MANIFEST.md exists with > 0 testable surfaces |
+| research | codebase-map | Research complete (non-blocking — continues even if no research output) |
 | codebase-map | analyze | At least 4 of 8 codebase map documents exist |
 | analyze | testid-inject | QA_ANALYSIS.md exists AND frontend components detected |
 | analyze | plan | QA_ANALYSIS.md + TEST_INVENTORY.md exist (skip testid-inject if no frontend) |
@@ -249,6 +250,7 @@ Each agent owns specific artifacts. No agent may produce artifacts assigned to a
 | Agent | Reads | Produces | Template |
 |-------|-------|----------|----------|
 | qa-scanner | repo source files, package.json, file tree | SCAN_MANIFEST.md | templates/scan-manifest.md |
+| qa-project-researcher | SCAN_MANIFEST.md, repo source files, Context7 MCP, WebSearch, WebFetch | TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md | -- |
 | qa-codebase-mapper | SCAN_MANIFEST.md, repo source files, CLAUDE.md | TESTABILITY.md, TEST_SURFACE.md, RISK_MAP.md, CRITICAL_PATHS.md, CODE_PATTERNS.md, API_CONTRACTS.md, TEST_ASSESSMENT.md, COVERAGE_GAPS.md | -- |
 | qa-analyzer | SCAN_MANIFEST.md, codebase map documents, CLAUDE.md | QA_ANALYSIS.md, TEST_INVENTORY.md, QA_REPO_BLUEPRINT.md (Option 1) or GAP_ANALYSIS.md (Option 2/3) | templates/qa-analysis.md, templates/test-inventory.md, templates/qa-repo-blueprint.md, templates/gap-analysis.md |
 | qa-planner | TEST_INVENTORY.md, QA_ANALYSIS.md, codebase map documents | Generation plan (internal) | -- |
@@ -257,7 +259,6 @@ Each agent owns specific artifacts. No agent may produce artifacts assigned to a
 | qa-e2e-runner | generated E2E test files, POM files, CLAUDE.md, live application | E2E_RUN_REPORT.md, fixed test/POM files with real locators | -- |
 | qa-testid-injector | repo source files, SCAN_MANIFEST.md, CLAUDE.md | TESTID_AUDIT_REPORT.md, modified source files with data-testid attributes | templates/scan-manifest.md, templates/testid-audit-report.md |
 | qa-bug-detective | test execution results, test source files, CLAUDE.md | FAILURE_CLASSIFICATION_REPORT.md | templates/failure-classification.md |
-| qa-project-researcher | SCAN_MANIFEST.md, repo source files | TESTING_STACK.md, FRAMEWORK_CAPABILITIES.md, API_TESTING_STRATEGY.md, E2E_STRATEGY.md | -- |
 
 **Rule:** An agent MUST NOT produce artifacts assigned to another agent.
 
@@ -398,13 +399,14 @@ Each agent operates on the same branch. No worktree splits are needed for this s
 
 Respect stage transitions from the Agent Pipeline section:
 1. qa-scanner runs first (no dependencies)
-2. qa-codebase-mapper runs after scanner (depends on SCAN_MANIFEST.md, spawns 4 parallel focus agents)
-3. qa-analyzer and qa-testid-injector run after codebase-map (both depend on SCAN_MANIFEST.md + codebase map documents)
-4. qa-planner runs after analyzer (depends on QA_ANALYSIS.md + TEST_INVENTORY.md + codebase map documents)
-5. qa-executor runs after planner (depends on generation plan + codebase map documents)
-6. qa-validator runs after executor (depends on generated test files)
-7. qa-e2e-runner runs after validator (depends on E2E test files + live application)
-8. qa-bug-detective runs after e2e-runner or validator if failures (depends on test results)
+2. qa-project-researcher runs after scanner (depends on SCAN_MANIFEST.md, uses Context7 MCP — non-blocking, pipeline continues if it fails)
+3. qa-codebase-mapper runs after researcher (depends on SCAN_MANIFEST.md, spawns 4 parallel focus agents)
+4. qa-analyzer and qa-testid-injector run after codebase-map (both depend on SCAN_MANIFEST.md + codebase map documents + research documents if available)
+5. qa-planner runs after analyzer (depends on QA_ANALYSIS.md + TEST_INVENTORY.md + codebase map documents)
+6. qa-executor runs after planner (depends on generation plan + codebase map documents + research documents if available + Context7 MCP)
+7. qa-validator runs after executor (depends on generated test files)
+8. qa-e2e-runner runs after validator (depends on E2E test files + live application + Context7 MCP)
+9. qa-bug-detective runs after e2e-runner or validator if failures (depends on test results + Context7 MCP)
 
 ### Auto-Advance Mode
 
@@ -428,12 +430,14 @@ Every agent MUST read its required inputs before producing any output. Failure t
 | Agent | MUST Read Before Producing Output |
 |-------|-----------------------------------|
 | qa-scanner | package.json (or equivalent), folder tree structure, all source file extensions to detect framework and language |
-| qa-analyzer | SCAN_MANIFEST.md (complete, verified), CLAUDE.md (all QA standards sections) |
+| qa-project-researcher | SCAN_MANIFEST.md, repo source files, MY_PREFERENCES.md. Uses Context7 MCP as primary source. |
+| qa-analyzer | SCAN_MANIFEST.md (complete, verified), CLAUDE.md (all QA standards sections), research documents (if available) |
 | qa-planner | TEST_INVENTORY.md (all test cases), QA_ANALYSIS.md (architecture and risk context) |
-| qa-executor | TEST_INVENTORY.md (test cases to implement), CLAUDE.md (POM rules, locator hierarchy, assertion rules, naming conventions, quality gates) |
+| qa-executor | TEST_INVENTORY.md (test cases to implement), CLAUDE.md (POM rules, locator hierarchy, assertion rules, naming conventions, quality gates), research documents (if available). Must query Context7 MCP before generating code. |
 | qa-validator | CLAUDE.md (quality gates, locator tiers, assertion rules), all generated test files to validate |
 | qa-testid-injector | SCAN_MANIFEST.md (component file list), CLAUDE.md (data-testid Convention section for naming rules) |
-| qa-bug-detective | Test execution output (stdout/stderr, exit codes), test source files (to read the failing code), CLAUDE.md (classification rules) |
+| qa-bug-detective | Test execution output (stdout/stderr, exit codes), test source files (to read the failing code), CLAUDE.md (classification rules), research documents (if available). Must query Context7 MCP before auto-fixing. |
+| qa-e2e-runner | Generated E2E test files, POM files, CLAUDE.md, live application, research documents (if available). Must query Context7 MCP before fixing locators. |
 
 ### Handoff Patterns
 

package/README.md

@@ -6,7 +6,7 @@
 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
+scan → research → map → analyze → plan → generate → validate → deliver
 ```
 
 ---
@@ -25,6 +25,7 @@ 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` |
+| **Research** | Investigates testing ecosystem via Context7 MCP and official docs | `TESTING_STACK.md`, `FRAMEWORK_CAPABILITIES.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` |
@@ -142,6 +143,7 @@ Runs the full pipeline end-to-end: scan, map, analyze, plan, generate, validate,
 | Command | Purpose |
 |---------|---------|
 | `/qa-start` | Full pipeline end-to-end (scan through PR) |
+| `/qa-research` | Research testing ecosystem via Context7 MCP |
 | `/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 |

package/agents/qaa-bug-detective.md

@@ -26,9 +26,59 @@ Read ALL of the following files BEFORE classifying any failures. Do NOT skip.
 
 - **~/.claude/qaa/MY_PREFERENCES.md** (optional -- read if exists). User's personal QA preferences saved by the qa-learner skill. If a preference conflicts with CLAUDE.md, the preference wins (it is a user override). Check for rules about: framework choices, assertion style, language preferences.
 
+- **Codebase map documents** (optional -- read if they exist in `.qa-output/codebase/`):
+  - **CODE_PATTERNS.md** -- Naming conventions, import patterns
+  - **API_CONTRACTS.md** -- API shapes for diagnosing API test failures
+  - **TEST_SURFACE.md** -- Function signatures for diagnosing unit test failures
+  - **TESTABILITY.md** -- Mock boundaries for diagnosing mock-related failures
+
+- **Research documents** (optional -- read if they exist in `.qa-output/research/`):
+  - **FRAMEWORK_CAPABILITIES.md** -- Verified framework API, selector syntax, assertion patterns. Critical for writing correct auto-fixes.
+  - **TESTING_STACK.md** -- Recommended stack configuration. Useful for diagnosing configuration-related failures.
+  If these files exist, use them as the primary source for framework-specific syntax when auto-fixing.
+
 Note: Read these files in full. Extract the decision tree, evidence field requirements, confidence level definitions, and auto-fix eligibility rules. These define your classification contract and output format.
 </required_reading>
 
+<context7_verification>
+
+## Non-negotiable: Framework Verification via Context7 Before Auto-Fixing
+
+**BEFORE auto-fixing any TEST CODE ERROR**, the bug-detective MUST verify the correct fix syntax using Context7 MCP. An auto-fix that uses incorrect syntax (wrong selector engine, wrong API method, wrong import path) is worse than no fix at all — it introduces a new TEST CODE ERROR.
+
+### When to query Context7
+
+1. **When detecting an unfamiliar framework** — if the test files use a framework you haven't seen in the research documents (e.g., Robot Framework, Selenium WebDriver, TestCafe), query Context7 before classifying or fixing:
+   ```
+   mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "selector syntax locator API" })
+   ```
+
+2. **Before writing any auto-fix that changes selectors or locators** — verify the correct syntax for the specific framework:
+   ```
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "{specific selector pattern}" })
+   ```
+
+3. **Before writing any auto-fix that changes assertion syntax** — verify the correct assertion API:
+   ```
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "assertion API expect" })
+   ```
+
+4. **When diagnosing failures that might be caused by framework API changes** — a test that used to pass but now fails may be using a deprecated API. Query Context7 for the current API.
+
+### Auto-fix validation rule
+
+Every auto-fix MUST have its syntax verified against Context7 or research documents before being applied. If Context7 is unavailable and no research documents cover the framework, downgrade the fix confidence to MEDIUM (which means it will be flagged for review instead of auto-applied).
+
+### If Context7 is unavailable
+
+If Context7 MCP is not connected or `resolve-library-id` fails:
+1. Use WebFetch to access official documentation
+2. Flag in MCP evidence file: `context7_available: false, fallback: webfetch`
+3. If neither source can verify the fix syntax, do NOT auto-fix — classify as TEST CODE ERROR but set confidence to MEDIUM so it gets flagged for user review instead of auto-applied
+
+</context7_verification>
+
 <process>
 
 <step name="read_inputs" priority="first">
@@ -509,6 +559,13 @@ Before considering the classification complete, verify ALL of the following.
 - [ ] Recommendations are grouped by category and specific to the failures found (not generic advice)
 - [ ] INCONCLUSIVE entries (if any) explain what information is missing
 
+**Context7 verification checks:**
+
+- [ ] Context7 was queried for the framework's syntax before writing any auto-fix that changes selectors or assertions
+- [ ] If research documents exist (`.qa-output/research/`), FRAMEWORK_CAPABILITIES.md was read before auto-fixing
+- [ ] If the test framework is not covered by research documents, Context7 was queried for it
+- [ ] No auto-fix was applied using unverified syntax (all fix syntax confirmed via Context7, research docs, or official docs)
+
 **Additional detective-specific checks:**
 
 - [ ] Test suite was actually executed (not static analysis) -- real test runner output captured with stdout, stderr, and exit code

package/agents/qaa-e2e-runner.md

@@ -27,8 +27,57 @@ Read ALL of the following files BEFORE running any tests. Do NOT skip.
 - **Codebase map documents** (optional -- read if they exist in `.qa-output/codebase/`):
   - **CODE_PATTERNS.md** -- Naming conventions to match when fixing test code
   - **TEST_SURFACE.md** -- Testable entry points for reference
+
+- **Research documents** (optional -- read if they exist in `.qa-output/research/`):
+  - **FRAMEWORK_CAPABILITIES.md** -- Verified framework API, selector syntax, patterns. Use as primary reference for correct syntax when fixing locators and assertions.
+  - **E2E_STRATEGY.md** -- E2E patterns, POM patterns, selector strategies for this project's stack.
+  If these files exist, use them as the primary source for framework-specific syntax when fixing code.
+
+- **Locator Registry** (optional -- read if it exists):
+  - **`.qa-output/locators/LOCATOR_REGISTRY.md`** -- Central index of all locators extracted from the live app.
+  - **`.qa-output/locators/{feature}.locators.md`** -- Per-feature locator files.
 </required_reading>
 
+<context7_verification>
+
+## Non-negotiable: Framework Verification via Context7
+
+**BEFORE fixing any locator or assertion**, the e2e-runner MUST verify the correct syntax using Context7 MCP. This is critical when the test framework is not standard Playwright JS/TS (e.g., Robot Framework, Cypress, Selenium, pytest).
+
+### When to query Context7
+
+1. **At the start of the run** (once per framework detected):
+   - Detect the framework from test file imports and config (Playwright, Cypress, Robot Framework, etc.)
+   - Query Context7 for the framework's selector/locator syntax:
+   ```
+   mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "selector syntax locator API" })
+   ```
+
+2. **When fixing locators** — before rewriting a locator, verify the correct syntax for the framework:
+   - Playwright JS/TS: `page.getByTestId()`, `page.getByRole()`, `page.locator()`
+   - Cypress: `cy.get('[data-cy="..."]')`, `cy.findByRole()`
+   - Robot Framework Browser: `Get Element`, `Click`, selectors use `id=`, `css=`, `text=` engines
+   - Other frameworks: query Context7 first, do NOT guess
+
+3. **When the framework is unfamiliar** — if the test files use a framework you haven't queried yet, STOP and query Context7 before making any changes.
+
+### Priority order for syntax decisions
+
+1. **Context7 query result** — always current, most authoritative
+2. **Research documents** (`.qa-output/research/FRAMEWORK_CAPABILITIES.md`) — verified
+3. **CLAUDE.md examples** — general patterns
+4. **Training data** — last resort
+
+### If Context7 is unavailable
+
+If Context7 MCP is not connected or `resolve-library-id` fails:
+1. Use WebFetch to access official documentation
+2. Flag in MCP evidence file: `context7_available: false, fallback: webfetch`
+3. If neither Context7 nor WebFetch can resolve the framework syntax, do NOT guess — flag the fix as INCONCLUSIVE and report to user
+
+</context7_verification>
+
 <tools>
 This agent uses the Playwright MCP browser tools for all browser interaction:
 
@@ -449,6 +498,8 @@ E2E runner is complete when:
 - [ ] Tests were executed against the live app
 - [ ] Failures were diagnosed using browser tools (snapshot, screenshot, evaluate)
 - [ ] Fixable issues (locators, assertions) were auto-fixed (up to 5 loops)
+- [ ] Context7 was queried for the framework's selector syntax before fixing any locators
+- [ ] If research documents exist (`.qa-output/research/`), FRAMEWORK_CAPABILITIES.md was read
 - [ ] Application bugs were classified with evidence (not auto-fixed)
 - [ ] E2E_RUN_REPORT.md was written with full results
 - [ ] Locator registry updated with all real locators discovered during execution (`.qa-output/locators/`)

package/agents/qaa-executor.md

@@ -60,8 +60,58 @@ Read ALL of the following files BEFORE producing any output. The executor's code
   If these files exist, they enable the executor to generate higher-quality tests that match the project's actual code patterns and API shapes.
 
 Note: The executor MUST read CLAUDE.md POM rules and locator tiers before writing any page object or test file. These rules are non-negotiable and must be applied to every generated file.
+
+- **Research documents** (optional -- read if they exist in `.qa-output/research/`):
+  - **TESTING_STACK.md** -- Recommended test framework, assertion libraries, mock strategies. Verified against current docs via Context7.
+  - **FRAMEWORK_CAPABILITIES.md** -- Full capabilities of the detected test framework: API, patterns, pitfalls, selector syntax. This is the most important research file for the executor.
+  - **API_TESTING_STRATEGY.md** -- API testing patterns, contract testing, auth testing.
+  - **E2E_STRATEGY.md** -- E2E framework patterns, POM patterns, selector strategies.
+  If these files exist, use them as the primary source for framework-specific syntax and patterns. They contain verified, up-to-date information from Context7 and official docs.
+
 </required_reading>
 
+<context7_verification>
+
+## Non-negotiable: Framework Verification via Context7
+
+**BEFORE generating any test file, POM, or fixture**, the executor MUST verify the framework's current API and syntax using Context7 MCP. This applies to ALL frameworks — including Playwright, Cypress, Jest, and other "well-known" frameworks. Training data may be outdated; Context7 provides current documentation.
+
+### When to query Context7
+
+1. **At the start of generation** (once per framework detected):
+   ```
+   mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "{framework} selector syntax and locator API" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "{framework} assertion API" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "{framework} configuration and setup" })
+   ```
+
+2. **When generating for a framework not covered by research documents** — if the user requests a framework (e.g., Robot Framework, Selenium, pytest) and `.qa-output/research/FRAMEWORK_CAPABILITIES.md` either does not exist or covers a different framework:
+   ```
+   mcp__context7__resolve-library-id({ libraryName: "{new-framework}" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "getting started setup imports" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "selector syntax locator API" })
+   mcp__context7__query-docs({ libraryId: "{resolved-id}", query: "assertion API expect" })
+   ```
+
+3. **When writing syntax you are not 100% certain about** — if you hesitate on an import path, method name, or API signature, query Context7 before writing it. Do NOT guess.
+
+### Priority order for framework information
+
+1. **Context7 query result** — most authoritative, always current
+2. **Research documents** (`.qa-output/research/`) — verified but may not cover all details
+3. **CLAUDE.md examples** — general patterns, may be outdated for specific framework versions
+4. **Training data** — last resort, flag as LOW confidence if used alone
+
+### If Context7 is unavailable
+
+If the Context7 MCP is not connected or `resolve-library-id` fails for the requested framework:
+1. Use WebFetch to access official documentation directly
+2. Flag in MCP evidence file: `context7_available: false, fallback: webfetch`
+3. Continue with WebFetch results, but mark generated code as MEDIUM confidence
+
+</context7_verification>
+
 <process>
 
 <step name="read_inputs" priority="first">
@@ -658,6 +708,13 @@ Before considering the executor's work complete, verify ALL of the following.
 - [ ] Priority assigned to every test case (P0, P1, or P2)
 - [ ] Framework matches what the project already uses
 
+**Context7 verification checks:**
+
+- [ ] Context7 was queried for the framework's selector/locator API before generating POM files
+- [ ] Context7 was queried for the framework's assertion API before generating test specs
+- [ ] If research documents exist (`.qa-output/research/`), they were read before generation
+- [ ] If the requested framework differs from what research documents cover, Context7 was queried for the new framework
+
 **Additional executor-specific checks:**
 
 - [ ] All planned files exist on disk (every file_path from generation plan verified)

package/agents/qaa-project-researcher.md

@@ -1,7 +1,7 @@
 ---
 name: qaa-project-researcher
-description: Researches testing ecosystem for a project's stack. Investigates framework capabilities, best practices, and testing patterns. Produces research files consumed by analyzer and planner agents.
-tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch
+description: Researches testing ecosystem for a project's stack. Investigates framework capabilities, best practices, and testing patterns using Context7 MCP as primary source. Produces research files consumed by all downstream QA agents.
+tools: Read, Write, Bash, Grep, Glob, WebSearch, WebFetch, mcp__context7__resolve-library-id, mcp__context7__query-docs
 color: cyan
 ---
 
@@ -191,7 +191,7 @@ Answer these for every project (depth varies by mode):
 
 <output_formats>
 
-All output files are written to the path specified by the orchestrator (typically `specs/research/` or `.planning/research/`). If no path is specified, write to the current working directory.
+All output files are written to the path specified by the orchestrator (typically `.qa-output/research/`). If no path is specified, write to `.qa-output/research/`.
 
 **Every output file follows this common structure:**
 
@@ -295,6 +295,26 @@ Return one of these to the orchestrator:
 
 </structured_returns>
 
+<version_awareness>
+
+## Version Detection and Reporting
+
+**Always detect the version the project currently uses** from `package.json`, `requirements.txt`, `go.mod`, lock files, or config files. Generate all research and syntax examples targeting the version in use — never assume the latest version.
+
+**Informational note about newer versions:** At the end of each output file, include a section:
+
+```markdown
+## Version Note (Informational)
+
+- **Project version:** {framework} {version detected from project}
+- **Latest stable version:** {latest version from Context7 or official docs}
+- **Notable changes since project version:** {brief list of relevant changes, if any}
+```
+
+This is informational only — do NOT recommend upgrading. The user decides if and when to upgrade. All syntax, examples, and patterns in the research must target the version the project currently uses.
+
+</version_awareness>
+
 <success_criteria>
 
 Research is complete when:

package/commands/qa-create-test.md

@@ -137,7 +137,7 @@ App URL: {url or "auto-detect"}
 
 Task(
   prompt="
-    <objective>Generate test files for the specified feature following CLAUDE.md standards, using codebase map for context</objective>
+    <objective>Generate test files for the specified feature following CLAUDE.md standards, using codebase map and research documents for context. Query Context7 MCP to verify framework syntax before generating code.</objective>
     <execution_context>@agents/qaa-executor.md</execution_context>
     <files_to_read>
     - CLAUDE.md
@@ -148,6 +148,10 @@ Task(
     - .qa-output/codebase/API_CONTRACTS.md (if exists)
     - .qa-output/codebase/TEST_SURFACE.md (if exists)
     - .qa-output/codebase/TESTABILITY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/E2E_STRATEGY.md (if exists)
+    - .qa-output/research/API_TESTING_STRATEGY.md (if exists)
+    - .qa-output/research/TESTING_STACK.md (if exists)
     </files_to_read>
     <parameters>
     user_input: $ARGUMENTS
@@ -162,12 +166,14 @@ Task(
 
 Task(
   prompt="
-    <objective>Run generated E2E tests against live application, capture real locators, fix mismatches, loop until pass</objective>
+    <objective>Run generated E2E tests against live application, capture real locators, fix mismatches, loop until pass. Query Context7 MCP to verify framework selector syntax before fixing locators.</objective>
     <execution_context>@agents/qaa-e2e-runner.md</execution_context>
     <files_to_read>
     - CLAUDE.md
     - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
     - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/E2E_STRATEGY.md (if exists)
     - {generated E2E test files from executor return}
     - {generated POM files from executor return}
     </files_to_read>

package/commands/qa-fix.md

@@ -331,12 +331,14 @@ If `--run` flag is also present and E2E test files exist, invoke E2E runner afte
 
 Task(
   prompt="
-    <objective>Run E2E tests against live application, capture real locators, fix mismatches, loop until pass</objective>
+    <objective>Run E2E tests against live application, capture real locators, fix mismatches, loop until pass. Query Context7 MCP to verify framework selector syntax before fixing locators.</objective>
     <execution_context>@agents/qaa-e2e-runner.md</execution_context>
     <files_to_read>
     - CLAUDE.md
     - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
     - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/E2E_STRATEGY.md (if exists)
     - {E2E test files from validated directory}
     - {POM files from validated directory}
     </files_to_read>
@@ -366,7 +368,7 @@ Fix mode runs in two phases: **analyze first, then fix after user confirmation.*
 
 Task(
   prompt="
-    <objective>Run tests and classify failures. Do NOT auto-fix anything yet — this is the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available — navigate to failing pages, snapshot DOM, reproduce actions, and screenshot failure state for evidence.</objective>
+    <objective>Run tests and classify failures. Do NOT auto-fix anything yet — this is the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available — navigate to failing pages, snapshot DOM, reproduce actions, and screenshot failure state for evidence. Query Context7 MCP to verify framework syntax when diagnosing failures.</objective>
     <execution_context>@agents/qaa-bug-detective.md</execution_context>
     <files_to_read>
     - CLAUDE.md
@@ -376,6 +378,8 @@ Task(
     - .qa-output/codebase/API_CONTRACTS.md (if exists)
     - .qa-output/codebase/TEST_SURFACE.md (if exists)
     - .qa-output/codebase/TESTABILITY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/TESTING_STACK.md (if exists)
     </files_to_read>
     <parameters>
     user_input: $ARGUMENTS
@@ -435,7 +439,7 @@ Proceed with auto-fixes? [yes / modify / cancel]
 
 Task(
   prompt="
-    <objective>Auto-fix the confirmed TEST CODE ERRORS from the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available — navigate to failing pages, snapshot DOM, reproduce actions, and screenshot failure state for evidence.</objective>
+    <objective>Auto-fix the confirmed TEST CODE ERRORS from the analysis phase. Use Playwright MCP to reproduce E2E failures in the browser when available. Query Context7 MCP to verify correct framework syntax before applying any fix.</objective>
     <execution_context>@agents/qaa-bug-detective.md</execution_context>
     <files_to_read>
     - CLAUDE.md
@@ -445,6 +449,8 @@ Task(
     - .qa-output/codebase/API_CONTRACTS.md (if exists)
     - .qa-output/codebase/TEST_SURFACE.md (if exists)
     - .qa-output/codebase/TESTABILITY.md (if exists)
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - .qa-output/research/TESTING_STACK.md (if exists)
     - .qa-output/FAILURE_CLASSIFICATION_REPORT.md
     </files_to_read>
     <parameters>

package/commands/qa-research.md

@@ -0,0 +1,157 @@
+# QA Research
+
+Research the testing ecosystem for the current project. Investigates framework capabilities, best practices, selector syntax, and testing patterns using Context7 MCP and official documentation. Produces research files consumed by all downstream QA agents (analyzer, planner, executor, validator).
+
+## Usage
+
+```
+/qa-research [options]
+```
+
+### Options
+
+- `--focus <mode>` — research mode (default: `stack-testing`)
+  - `stack-testing` — full stack analysis: test runner, assertions, mocking, E2E framework, CI/CD patterns
+  - `framework-deep-dive` — deep dive into the detected/specified framework: full API, patterns, pitfalls, selector syntax
+  - `api-testing` — API testing strategy: endpoint patterns, contract testing, auth testing, error testing
+  - `e2e-strategy` — E2E strategy: framework comparison, POM patterns, selector strategies, visual testing
+- `--dev-repo <path>` — path to developer repository (default: current directory)
+
+### Mode Detection
+
+```
+if --focus framework-deep-dive:
+  MODE = "framework-deep-dive"
+elif --focus api-testing:
+  MODE = "api-testing"
+elif --focus e2e-strategy:
+  MODE = "e2e-strategy"
+else:
+  MODE = "stack-testing"
+```
+
+## What It Produces
+
+All output files are written to `.qa-output/research/`.
+
+| Mode | Output |
+|------|--------|
+| stack-testing | `TESTING_STACK.md` (+ `API_TESTING_STRATEGY.md` and `E2E_STRATEGY.md` if project has APIs and frontend) |
+| framework-deep-dive | `FRAMEWORK_CAPABILITIES.md` |
+| api-testing | `API_TESTING_STRATEGY.md` |
+| e2e-strategy | `E2E_STRATEGY.md` |
+
+These files are consumed by downstream agents:
+
+| File | Consumed By |
+|------|-------------|
+| `TESTING_STACK.md` | Analyzer (framework selection), Planner (dependency setup) |
+| `FRAMEWORK_CAPABILITIES.md` | Executor (idiomatic test writing), Validator (pattern checking), E2E Runner (correct syntax) |
+| `API_TESTING_STRATEGY.md` | Planner (API test case design), Executor (implementation patterns) |
+| `E2E_STRATEGY.md` | Planner (E2E scope decisions), Executor (POM and selector patterns) |
+
+## Instructions
+
+### Step 1: Initialize
+
+Parse `$ARGUMENTS` for flags.
+
+```bash
+MODE="stack-testing"
+DEV_REPO=""
+
+if echo "$ARGUMENTS" | grep -qE '\-\-focus'; then
+  MODE=$(echo "$ARGUMENTS" | grep -oE '\-\-focus\s+[^\s]+' | awk '{print $2}')
+fi
+
+if echo "$ARGUMENTS" | grep -qE '\-\-dev-repo'; then
+  DEV_REPO=$(echo "$ARGUMENTS" | grep -oE '\-\-dev-repo\s+[^\s]+' | awk '{print $2}')
+fi
+
+if [ -z "$DEV_REPO" ]; then
+  DEV_REPO=$(pwd)
+fi
+
+mkdir -p .qa-output/research
+```
+
+Print banner:
+```
+=== QA Research ===
+Mode: {MODE}
+Dev Repo: {DEV_REPO}
+Output: .qa-output/research/
+====================
+```
+
+### Step 2: Read Existing Context (if available)
+
+Read these files if they exist — they provide context to the researcher:
+
+- `.qa-output/SCAN_MANIFEST.md` — detected project stack from scanner
+- `CLAUDE.md` — QA standards that the research must align with
+- `~/.claude/qaa/MY_PREFERENCES.md` — user preferences (framework choices, conventions)
+
+### Step 3: Spawn Researcher Agent
+
+Task(
+  prompt="
+    <objective>Research the testing ecosystem for this project. Mode: {MODE}. Use Context7 MCP as the primary source for all framework and library questions. Verify everything against current documentation — do not rely on training data alone.</objective>
+    <execution_context>@agents/qaa-project-researcher.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/SCAN_MANIFEST.md (if exists)
+    </files_to_read>
+    <parameters>
+    mode: {MODE}
+    dev_repo_path: {DEV_REPO}
+    output_dir: .qa-output/research
+    </parameters>
+  "
+)
+
+### Step 4: Present Results
+
+After the researcher completes, summarize what was found:
+
+```
+=== Research Complete ===
+Mode: {MODE}
+Files produced: {list of files in .qa-output/research/}
+Framework detected: {name + version}
+Key findings:
+  - {finding 1}
+  - {finding 2}
+  - {finding 3}
+
+These files will be automatically consumed by downstream agents
+when you run /qa-create-test, /qa-fix, or /qa-start.
+=========================
+```
+
+$ARGUMENTS
+
+## MANDATORY verification — run ALL commands below, no exceptions, no skipping
+
+Before returning control, copy-paste and run this ENTIRE block. Do NOT decide which commands "apply" — run all of them every time. The output confirms what happened; you do not get to assume the answer.
+
+```bash
+echo "=== QA-RESEARCH CHECKLIST START ==="
+echo "1. Research output files:"
+ls .qa-output/research/ 2>/dev/null || echo "NO_RESEARCH_FILES"
+echo "2. TESTING_STACK.md content check:"
+head -20 .qa-output/research/TESTING_STACK.md 2>/dev/null || echo "NO_TESTING_STACK"
+echo "3. FRAMEWORK_CAPABILITIES.md content check:"
+head -20 .qa-output/research/FRAMEWORK_CAPABILITIES.md 2>/dev/null || echo "NO_FRAMEWORK_CAPABILITIES"
+echo "4. Context7 was used (check for confidence levels):"
+grep -c "HIGH\|MEDIUM\|LOW" .qa-output/research/*.md 2>/dev/null || echo "NO_CONFIDENCE_LEVELS"
+echo "5. Version information present:"
+grep -i "version" .qa-output/research/*.md 2>/dev/null | head -5 || echo "NO_VERSION_INFO"
+echo "=== QA-RESEARCH CHECKLIST END ==="
+```
+
+**Rules:**
+- Run the block AS-IS. Do not modify it. Do not split it. Do not skip lines.
+- If any output shows a problem (NO_RESEARCH_FILES after research completed), fix it before returning.
+- Do NOT mark this task as complete until the block has been executed and you have read every line of output.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "qaa-agent",
-  "version": "1.8.6",
+  "version": "1.9.0",
   "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"

package/workflows/qa-start.md

@@ -271,6 +271,66 @@ If SCAN_MANIFEST.md is missing, treat as stage failure. Set status to failed and
 
 </step>
 
+<step name="research">
+
+## Step 3b: Research Testing Ecosystem
+
+**State update -- mark research as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Research Status" running --"Status" "Researching testing ecosystem" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 1b: Project Researcher            |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Create output directory:**
+```bash
+mkdir -p ${output_dir}/research
+```
+
+**Spawn researcher agent:**
+```
+Agent(subagent_type="general-purpose",
+  prompt="
+    <objective>Research the testing ecosystem for this project. Use Context7 MCP as the primary source for all framework and library questions. Produce research documents consumed by downstream agents.</objective>
+    <execution_context>@agents/qaa-project-researcher.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - ${output_dir}/SCAN_MANIFEST.md
+    </files_to_read>
+    <parameters>
+    mode: stack-testing
+    dev_repo_path: {DEV_REPO}
+    output_dir: ${output_dir}/research
+    </parameters>
+  "
+)
+```
+
+**Verify research artifacts exist:**
+```bash
+ls ${output_dir}/research/*.md 2>/dev/null && echo "OK: Research files produced" || echo "WARNING: No research files produced"
+```
+
+**Research is non-blocking:** If the researcher fails or produces no output, the pipeline continues — downstream agents will fall back to Context7 queries directly. Log the warning but do NOT stop the pipeline.
+
+```bash
+if [ ! -f "${output_dir}/research/TESTING_STACK.md" ]; then
+  echo "WARNING: Research stage produced no output. Downstream agents will query Context7 directly."
+  node bin/qaa-tools.cjs state patch --"Research Status" "skipped (no output)" 2>/dev/null || true
+else
+  node bin/qaa-tools.cjs state patch --"Research Status" complete 2>/dev/null || true
+fi
+```
+
+</step>
+
 <step name="analyze">
 
 ## Step 4: Analyze Repository
@@ -301,6 +361,8 @@ Agent(subagent_type="general-purpose",
     <files_to_read>
     - {output_dir}/SCAN_MANIFEST.md
     - CLAUDE.md
+    - {output_dir}/research/TESTING_STACK.md (if exists)
+    - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
     </files_to_read>
     <parameters>
     mode: {mode}
@@ -528,6 +590,9 @@ Agent(subagent_type="general-purpose",
     - {output_dir}/GENERATION_PLAN.md
     - {output_dir}/TEST_INVENTORY.md (Option 1) or {output_dir}/GAP_ANALYSIS.md (Options 2/3)
     - CLAUDE.md
+    - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - {output_dir}/research/E2E_STRATEGY.md (if exists)
+    - {output_dir}/research/API_TESTING_STRATEGY.md (if exists)
     </files_to_read>
     <parameters>
     workflow_option: {option}
@@ -554,6 +619,9 @@ Agent(subagent_type="general-purpose",
     - {output_dir}/GENERATION_PLAN.md
     - {output_dir}/TEST_INVENTORY.md (Option 1) or {output_dir}/GAP_ANALYSIS.md (Options 2/3)
     - CLAUDE.md
+    - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - {output_dir}/research/E2E_STRATEGY.md (if exists)
+    - {output_dir}/research/API_TESTING_STRATEGY.md (if exists)
     </files_to_read>
     <parameters>
     workflow_option: {option}
@@ -745,6 +813,8 @@ Agent(subagent_type="general-purpose",
     - {test execution results -- from validator or direct test run}
     - {failing test source files -- paths from executor return}
     - CLAUDE.md
+    - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - {output_dir}/research/TESTING_STACK.md (if exists)
     </files_to_read>
     <parameters>
     output_path: {output_dir}/FAILURE_CLASSIFICATION_REPORT.md