qaa-agent 1.8.5 → 1.9.0

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 
 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
+
+- **Fix mode analyze-first flow in `/qa-fix`** — fix mode now runs in two phases: Phase 1 analyzes and classifies all failures without touching any files, then presents a Fix Plan to the user. Phase 2 executes auto-fixes only after explicit user confirmation. Users can refine the plan iteratively (add fixes, remove files, change approach) in a loop until satisfied, then approve or cancel. Replaces the previous fully-automatic fix behavior.
+- **Codebase map context for bug-detective** — `/qa-fix` fix mode now passes all 4 codebase map documents (`CODE_PATTERNS.md`, `API_CONTRACTS.md`, `TEST_SURFACE.md`, `TESTABILITY.md`) to the bug-detective agent via `files_to_read`. Previously the bug-detective classified failures without project-specific context, leading to less accurate classifications.
+- **Mandatory bash checklist in `/qa-fix`** — verification block at the end of `qa-fix.md` that forces the agent to run `ls`/`cat`/`grep` commands to confirm artifacts were produced (classification report, locator registry, codebase map, MCP evidence, test files). Matches the existing checklist pattern in `/qa-create-test`.
+
+### Changed
+
+- **Validator fix loops increased from 3 to 5** — `qaa-validator` agent now has up to 5 fix loop iterations (previously 3), matching the E2E runner's loop budget. Updated across all references: locked decision, fix loop logic, checkpoint return, confidence criteria table, and quality gate checks.
+
 ## [1.8.5] - 2026-04-17
 
 ### 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/agents/qaa-validator.md

@@ -25,7 +25,7 @@ Read ALL of the following files BEFORE performing any validation. Do NOT skip.
 
 - **templates/validation-report.md** -- Output format contract. Defines the 5 required sections (Summary, File Details, Unresolved Issues, Fix Loop Log, Confidence Level), all field definitions, confidence criteria table (HIGH/MEDIUM/LOW), worked example, and quality gate checklist (7 items). Your VALIDATION_REPORT.md output MUST match this template exactly.
 
-- **.claude/skills/qa-self-validator/SKILL.md** -- Defines the 4 validation layers (Syntax, Structure, Dependencies, Logic), pass criteria per layer, fix loop protocol (max 3 loops), and output format.
+- **.claude/skills/qa-self-validator/SKILL.md** -- Defines the 4 validation layers (Syntax, Structure, Dependencies, Logic), pass criteria per layer, fix loop protocol (max 5 loops), and output format.
 
 - **~/.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: assertion style, locator strategy, naming conventions, framework choices.
 
@@ -257,7 +257,7 @@ Attempt to fix issues found during validation layers. This step encodes ALL 8 lo
 
 **Locked Decision 2: Sequential, fail-fast** -- Layers run in order: Layer 1 (Syntax) -> Layer 2 (Structure) -> Layer 3 (Dependencies) -> Layer 4 (Logic). Fix Layer 1 issues before proceeding to check Layer 2. If Layer 1 fails, fix it and re-validate Layer 1 before moving to Layer 2.
 
-**Locked Decision 3: Max 3 loops** -- The fix loop runs at most 3 times. After 3 loops with unresolved issues, STOP and escalate.
+**Locked Decision 3: Max 5 loops** -- The fix loop runs at most 5 times. After 5 loops with unresolved issues, STOP and escalate.
 
 **Locked Decision 4: Generated files only** -- Only fix files listed in the generation plan. Never modify pre-existing test files.
 
@@ -280,7 +280,7 @@ Attempt to fix issues found during validation layers. This step encodes ALL 8 lo
 **Fix loop execution:**
 
 ```
-Loop iteration (max 3):
+Loop iteration (max 5):
   1. Run all 4 validation layers sequentially (fail-fast)
   2. If all layers PASS: exit loop, proceed to produce_report
   3. If any layer FAIL:
@@ -290,20 +290,20 @@ Loop iteration (max 3):
         - If MEDIUM or LOW: record as unresolved, do NOT apply
      b. Log this loop iteration: issues found, fixes applied, verification
      c. Re-validate from the FAILED layer (not from Layer 1 unless Layer 1 failed)
-     d. If this was loop 3: exit loop regardless of results
+     d. If this was loop 5: exit loop regardless of results
 ```
 
-**After 3 loops with unresolved issues:**
+**After 5 loops with unresolved issues:**
 
 STOP and return a checkpoint:
 
 ```
 CHECKPOINT_RETURN:
 completed: "Validated {N} files across 4 layers. Completed {loop_count} fix loops."
-blocking: "Unresolved validation issues after maximum 3 fix loops"
+blocking: "Unresolved validation issues after maximum 5 fix loops"
 details:
   files_validated: {N}
-  loops_completed: 3
+  loops_completed: 5
   issues_found: {total_count}
   issues_fixed: {fixed_count}
   unresolved:
@@ -314,6 +314,9 @@ details:
       why_not_fixed: "{reason auto-fix was not applied}"
 awaiting: "User decides: fix remaining issues manually, accept with warnings, or abort validation"
 ```
+
+**Note:** The validator now has 5 fix loop iterations (up from 3), matching the E2E runner's loop budget. This gives more room to resolve cascading issues where fixing one problem reveals another.
+```
 </step>
 
 <step name="produce_report">
@@ -391,8 +394,8 @@ Include the confidence criteria table:
 | Level | All Layers PASS | Unresolved Issues | Fix Loops Used | Description |
 |-------|----------------|-------------------|----------------|-------------|
 | HIGH | Yes | 0 | 0-1 | All validations pass with minimal or no fixes needed. Code is ready for delivery. |
-| MEDIUM | Yes (after fixes) | 0-2 minor | 2-3 | All layers eventually pass, but required multiple fix rounds. Minor issues may exist. |
-| LOW | No (any FAIL) | Any critical | 3 (max) | At least one layer still fails, or critical issues remain unresolved. Human review required before delivery. |
+| MEDIUM | Yes (after fixes) | 0-2 minor | 2-5 | All layers eventually pass, but required multiple fix rounds. Minor issues may exist. |
+| LOW | No (any FAIL) | Any critical | 5 (max) | At least one layer still fails, or critical issues remain unresolved. Human review required before delivery. |
 
 Followed by the specific confidence statement:
 `**{LEVEL}:** {one-sentence reasoning referencing specific metrics from the summary}`
@@ -477,8 +480,8 @@ Before considering validation complete, verify ALL of the following.
 - [ ] Only generated files were validated (not pre-existing test files) -- verify every file in the report appears in the generation plan file list
 - [ ] Layer 4 cross-checked existing test files for duplicate IDs and overlapping selectors to prevent collisions
 - [ ] Fix confidence correctly classified (HIGH auto-applied, MEDIUM/LOW flagged for review but NOT auto-applied)
-- [ ] Fix loop count did not exceed 3 iterations
-- [ ] If 3 loops exhausted with unresolved issues: CHECKPOINT_RETURN was provided to escalate to user
+- [ ] Fix loop count did not exceed 5 iterations
+- [ ] If 5 loops exhausted with unresolved issues: CHECKPOINT_RETURN was provided to escalate to user
 - [ ] Validator did NOT commit any files (no git add, no git commit, no qaa-tools commit)
 
 If any check fails, fix the issue before finalizing the output. Do not deliver a validation report that fails its own quality gate.

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

@@ -325,18 +325,20 @@ The validator runs 4 layers per file:
 - Cross-reference test locators against real DOM elements
 - Flag locators that don't match, auto-fix mismatches
 
-Max 3 fix loop iterations. Produces VALIDATION_REPORT.md.
+Max 5 fix loop iterations. Produces VALIDATION_REPORT.md.
 
 If `--run` flag is also present and E2E test files exist, invoke E2E runner after static validation:
 
 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>
@@ -357,20 +359,103 @@ Same as fix mode below but skip Step 4 (auto-fix). Only classify and report.
 
 ### FIX MODE (default)
 
+Fix mode runs in two phases: **analyze first, then fix after user confirmation.**
+
+#### Phase 1: Analyze & Present Plan (always runs)
+
 1. Read `CLAUDE.md` — classification rules, locator tiers, assertion quality.
-2. Invoke bug-detective agent:
+2. Invoke bug-detective agent in **classify-only mode** (no auto-fixes):
 
 Task(
   prompt="
-    <objective>Run tests, classify failures, and auto-fix TEST CODE ERRORS. 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
     - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
     - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
+    - .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
+    mode: classify-only
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+3. Present the analysis to the user as a **fix plan**:
+
+```
+=== FIX PLAN ===
+
+Tests run: {N}
+Passed: {N}
+Failed: {N}
+
+Failures classified:
+  APPLICATION BUG:    {N} (will NOT be touched)
+  TEST CODE ERROR:    {N} (can auto-fix)
+  ENVIRONMENT ISSUE:  {N} (resolution steps provided)
+  INCONCLUSIVE:       {N} (needs more info)
+
+Proposed auto-fixes (TEST CODE ERRORS only):
+  1. {file}:{line} — {description of fix} [HIGH confidence]
+  2. {file}:{line} — {description of fix} [HIGH confidence]
+  3. {file}:{line} — {description of fix} [MEDIUM — flagged for review]
+
+APPLICATION BUGs found (for developer action):
+  1. {file}:{line} — {description}
+  2. {file}:{line} — {description}
+
+Proceed with auto-fixes? [yes / modify / cancel]
+================
+```
+
+4. **Wait for user confirmation.** Do NOT proceed until the user approves. This is a refinement loop — repeat until the user is satisfied:
+
+   - **"yes"** / **"proceed"** / **"dale"** → continue to Phase 2
+   - **"cancel"** / **"no"** → stop, deliver only the FAILURE_CLASSIFICATION_REPORT.md (same as --classify)
+   - **Any other response** (feedback, modifications, additions) → treat as a refinement request:
+     - Adjust the fix plan based on the user's instructions (add fixes, remove fixes, change approach, add new checks)
+     - Re-present the updated Fix Plan showing what changed
+     - Wait for user confirmation again
+     - Repeat this loop until the user says "yes" or "cancel"
+
+   **Examples of refinement requests:**
+   - "esto está bien pero también quiero que arregles los imports de utils" → add that fix to the plan
+   - "no toques el archivo de login, dejalo como está" → remove that file from the plan
+   - "cambiá el selector por getByRole en vez de getByTestId" → update the proposed fix
+   - "agregá también una validación de que el status sea 200" → add assertion fix to the plan
+
+#### Phase 2: Execute Fixes (only after user confirmation)
+
+5. Invoke bug-detective agent in **fix mode** with the confirmed plan:
+
+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. 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
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists)
+    - .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>
+    user_input: $ARGUMENTS
+    mode: fix
     app_url: {auto-detect from test config baseURL, or ask user}
     </parameters>
   "
@@ -394,6 +479,35 @@ Task(
 - Element exists, wrong behavior → APPLICATION BUG
 - Page doesn't load → ENVIRONMENT ISSUE
 
-3. Present results. APPLICATION BUGs are reported for developer action, not auto-fixed.
+6. Present results. APPLICATION BUGs are reported for developer action, not auto-fixed.
 
 $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-FIX CHECKLIST START ==="
+echo "1. Failure classification report:"
+ls .qa-output/FAILURE_CLASSIFICATION_REPORT.md 2>/dev/null || echo "NO_CLASSIFICATION_REPORT"
+echo "2. Locator Registry:"
+ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
+echo "3. MY_PREFERENCES.md:"
+cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
+echo "4. Codebase map (context for bug-detective):"
+ls .qa-output/codebase/ 2>/dev/null || echo "NO_CODEBASE_MAP"
+echo "5. Test files in scope:"
+find tests/ cypress/ __tests__/ e2e/ spec/ -type f -name "*.spec.*" -o -name "*.test.*" -o -name "*.e2e.*" 2>/dev/null | head -20 || echo "NO_TEST_FILES_FOUND"
+echo "6. MCP evidence (if browser was used):"
+ls .qa-output/mcp-evidence/ 2>/dev/null || echo "NO_MCP_EVIDENCE"
+echo "7. Classification categories in report:"
+grep -cE "APPLICATION BUG|TEST CODE ERROR|ENVIRONMENT ISSUE|INCONCLUSIVE" .qa-output/FAILURE_CLASSIFICATION_REPORT.md 2>/dev/null || echo "NO_CLASSIFICATIONS"
+echo "=== QA-FIX 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_CLASSIFICATION_REPORT after fix mode completed), fix it before returning.
+- If output shows expected "not found" results (e.g., NO_MCP_EVIDENCE when no browser was used), that is fine — the point is you RAN the command instead of assuming the answer.
+- Do NOT mark this task as complete until the block has been executed and you have read every line of output.

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.5",
+  "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"
@@ -15,10 +15,6 @@
     "pytest",
     "ai-agent"
   ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Backhaus7997/qaa-testing.git"
-  },
   "author": "Backhaus7997",
   "license": "MIT",
   "dependencies": {

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