qaa-agent 1.9.1 → 1.9.5

package/commands/qa-create-test.md

@@ -1,365 +1,666 @@
-# QA Create Test
-
-Create, update, or generate tests from tickets — all in one command. Supports five modes: generate tests from code analysis, generate tests from a ticket (Jira/Linear/GitHub), create Test Cases in Azure DevOps from a work item, update/improve existing tests, or generate POM files only. Uses Playwright MCP to extract real locators from the live app when available.
-
-## Usage
-
-```
-/qa-create-test <feature-or-source> [options]
-```
-
-### Modes (auto-detected from arguments)
-
-| Mode | Trigger | Example |
-|------|---------|---------|
-| **From code** | Feature name (no URL, no path to tests) | `/qa-create-test login` |
-| **From ticket** | URL, shorthand (#123), or `--ticket` flag | `/qa-create-test https://github.com/org/repo/issues/42` |
-| **Azure DevOps** | `--ado` flag with work item ID or ADO URL | `/qa-create-test --ado 85508` |
-| **Update existing** | Path to existing test files or `--update` flag | `/qa-create-test --update tests/e2e/` |
-| **POM only** | `--pom-only` flag | `/qa-create-test --pom-only src/pages/` |
-
-### Options
-
-- `--dev-repo <path>` — path to developer repository (default: current directory)
-- `--app-url <url>` — URL of running application for E2E execution and locator extraction (auto-detects if not provided)
-- `--skip-run` — skip E2E execution, only generate and statically validate
-- `--ticket <source>` — force ticket mode with: URL, shorthand (#123, org/repo#123), file path, or plain text
-- `--update <path>` — force update mode: audit and improve existing tests at path
-- `--scope fix|improve|add|full` — for update mode only (default: full)
-- `--ado <work-item-id>` — Azure DevOps mode: read a work item and create Test Cases in ADO (accepts ID or full ADO URL)
-- `--area-path <path>` — (ADO mode) override area path for created test cases (default: source work item's area path)
-- `--iteration-path <path>` — (ADO mode) override iteration path for created test cases (default: source work item's iteration path)
-- `--skip-dedup` — (ADO mode) skip deduplication check against existing linked test cases
-- `--pom-only [path]` — generate only Page Object Model files (BasePage + feature POMs), no test specs
-- `--framework <name>` — override framework auto-detection (playwright, cypress, selenium) — used with --pom-only
-
-### Mode Detection Logic
-
-```
-if --pom-only:
-  MODE = "pom-only"
-elif --ado flag OR argument matches ADO URL (dev.azure.com, *.visualstudio.com):
-  MODE = "ado"
-elif argument matches URL pattern (github.com, atlassian.net, linear.app) OR contains "#" + digits OR --ticket flag:
-  MODE = "from-ticket"
-elif --update flag OR argument is path to existing test directory/files:
-  MODE = "update"
-else:
-  MODE = "from-code"
-```
-
-## What It Produces
-
-### From Code Mode
-- Test spec files (unit, API, E2E as appropriate)
-- Page Object Model files (for E2E tests)
-- Fixture files (test data)
-- Locator registry entries (`.qa-output/locators/`)
-- E2E_RUN_REPORT.md (if E2E tests ran against live app)
-
-### From Ticket Mode
-- TEST_CASES_FROM_TICKET.md — traceability matrix (AC → test case)
-- GENERATION_PLAN_TICKET.md — synthetic generation plan
-- Test spec files with `traces_to` fields linking back to ticket ACs
-- VALIDATION_REPORT.md
-
-### Azure DevOps Mode
-- Test Cases created directly in Azure DevOps (via `testplan_create_test_case`)
-- Test Cases linked to source work item via *Tested By* relationship
-- Tags applied: `Smoke`, `Regression`, `Critical`, `AutomationCandidate`, `NeedsReview`
-- `ai-tasks/ticket-{id}/test-cases.md` — structured report
-- Report attached to work item (if `ADO_MCP_AUTH_TOKEN` is set) or written to `Custom.QATestCasesReport` field (fallback)
-
-### Update Mode
-- QA_AUDIT_REPORT.md — current quality assessment
-- Improved test files (after user approval)
-
-## Instructions
-
-### Step 1: Detect Mode
-
-Parse `$ARGUMENTS` to determine mode using the detection logic above.
-
-Print mode banner:
-```
-=== QA Create Test ===
-Mode: {from-code | from-ticket | ado | update | pom-only}
-Target: {feature name | ticket URL | ADO work item ID | test path}
-App URL: {url or "auto-detect"}
-===========================
-```
-
----
-
-### FROM CODE MODE
-
-1. Read `CLAUDE.md` — POM rules, locator tiers, assertion rules, naming conventions, quality gates.
-1b. Read `~/.claude/qaa/MY_PREFERENCES.md` if it exists — user's personal QA preferences override CLAUDE.md defaults when there is a conflict.
-2. Read existing analysis artifacts if available:
-   - `.qa-output/QA_ANALYSIS.md` — architecture context
-   - `.qa-output/TEST_INVENTORY.md` — pre-defined test cases for this feature
-3. **Check for codebase map** (`.qa-output/codebase/`):
-   - Look for: `CODE_PATTERNS.md`, `API_CONTRACTS.md`, `TEST_SURFACE.md`, `TESTABILITY.md`
-   - If at least 2 of these files exist: read them all for project context (naming conventions, API shapes, testable surfaces).
-   - **If NONE of these files exist: STOP and tell the user:**
-     ```
-     ⚠ No codebase map found (.qa-output/codebase/ is empty or missing).
-
-     The codebase map provides critical context: naming conventions, API contracts,
-     testable surfaces, and project structure. Without it, generated tests will lack
-     project-specific context and may not follow your repo's conventions.
-
-     Run /qa-map first to generate the codebase map, then re-run /qa-create-test.
-
-     To skip this check and proceed without context: re-run with --skip-map
-     ```
-     Only proceed without codebase map if the user explicitly passes `--skip-map`.
-
-4. **Check existing locator registry and extract new locators from live app:**
-
-   a. Read `.qa-output/locators/LOCATOR_REGISTRY.md` if it exists.
-
-   b. If locators for this feature already exist in the registry AND no `--app-url` was provided: reuse cached locators.
-
-   c. If locators are missing or `--app-url` was provided: Use Playwright MCP to navigate the app and extract real locators:
-      ```
-      mcp__playwright__browser_navigate({ url: "{app_url}/{feature_path}" })
-      mcp__playwright__browser_snapshot()
-      ```
-      Extract all data-testid, ARIA roles, labels, placeholders.
-      Navigate through multi-page flows if needed.
-      Write per-feature locator file to `.qa-output/locators/{feature}.locators.md`.
-      Update the registry `.qa-output/locators/LOCATOR_REGISTRY.md`.
-
-   If no app URL available and no locators in registry, skip — executor proposes locators from source code.
-
-5. Invoke executor agent to generate test files:
-
-Task(
-  prompt="
-    <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
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
-    - .qa-output/locators/{feature}.locators.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/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
-    mode: feature-test
-    codebase_map_dir: .qa-output/codebase
-    locator_registry: .qa-output/locators/LOCATOR_REGISTRY.md
-    </parameters>
-  "
-)
-
-6. If E2E test files were generated AND `--skip-run` was NOT passed, invoke E2E runner:
-
-Task(
-  prompt="
-    <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>
-    <parameters>
-    app_url: {from --app-url flag or auto-detect}
-    output_dir: .qa-output
-    </parameters>
-  "
-)
-
-7. Present results with file counts and suggest `/qa-pr`.
-
----
-
-### FROM TICKET MODE
-
-1. Read `CLAUDE.md` — all QA standards.
-2. Execute the ticket workflow end-to-end:
-
-Follow the workflow defined in `@workflows/qa-from-ticket.md` end-to-end.
-Preserve all workflow gates (ticket parsing, acceptance criteria extraction, traceability matrix, validation).
-
-Key steps in the workflow:
-- Parse ticket source (GitHub URL, Jira URL, Linear URL, file, or plain text)
-- Fetch ticket content (via `gh issue view`, WebFetch, or file read)
-- Extract acceptance criteria, user stories, edge cases
-- Scan dev repo for related source files
-- Extract locators from live app via Playwright MCP (if app URL available)
-- Generate test cases with traceability matrix (every AC maps to ≥1 test case)
-- Spawn executor agent to produce test files
-- Spawn validator agent for 4-layer validation
-- Print summary with AC coverage and traceability
-
-**Traceability guarantee:** Every acceptance criterion maps to at least one test case via the `traces_to` field.
-
-**Supported ticket sources:**
-
-| Format | Example | Detection |
-|--------|---------|-----------|
-| GitHub Issue URL | `https://github.com/org/repo/issues/123` | Contains `github.com` + `/issues/` |
-| GitHub shorthand | `org/repo#123` or `#123` | Contains `#` + digits |
-| Jira URL | `https://company.atlassian.net/browse/PROJ-123` | Contains `.atlassian.net/browse/` |
-| Linear URL | `https://linear.app/team/issue/TEAM-123` | Contains `linear.app` |
-| File path | `./tickets/feature-spec.md` | Path exists on disk |
-| Plain text | `"As a user I want to..."` | None of the above match |
-
----
-
-### ADO MODE (Azure DevOps)
-
-Create Test Cases directly in Azure DevOps from a work item. Reads the work item content (repro steps, acceptance criteria, comments, attachments), designs test cases with boundary detection and deduplication, and creates them in ADO with full traceability.
-
-**Prerequisites:** ADO MCP server must be connected (provides `wit_get_work_item`, `testplan_create_test_case`, etc.).
-
-Execute the full ADO workflow defined in `@commands/qa-create-test-ado.md`:
-
-1. **Phase 1** — Read pipeline context: CLAUDE.md, MY_PREFERENCES.md, codebase map, locator registry
-2. **Phase 2** — Retrieve work item with relations, comments, and attachments
-3. **Phase 2b** — Deduplication check against existing linked test cases (skip with `--skip-dedup`)
-4. **Phase 3** — Extract test source content based on work item type (Bug → Repro Steps, User Story → Acceptance Criteria)
-5. **Phase 4** — Design test cases with boundary value detection, tagging rules, confidence scoring, and preconditions
-6. **Phase 5** — Create test cases in ADO via `testplan_create_test_case`, link via *Tested By*, set tags
-7. **Phase 6** — Generate structured report to `ai-tasks/ticket-{id}/test-cases.md`
-8. **Phase 7** — Attach report to source work item
-
-**Key features:**
-- Boundary value triplets: detects `max`, `min`, `limit`, `threshold` keywords with numeric values → generates N-1, N, N+1 test cases
-- Deduplication: checks existing linked TCs before creating, prevents duplicates
-- Confidence scoring: `Specified` (explicit source) vs `Draft` (inferred, tagged `NeedsReview`)
-- Cross-references codebase map for project-specific context when available
-- Supports `--area-path` and `--iteration-path` overrides
-
-For the complete step-by-step process, see `@commands/qa-create-test-ado.md`.
-
----
-
-### UPDATE MODE
-
-1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules, POM rules.
-2. Invoke validator agent in audit mode:
-
-Task(
-  prompt="
-    <objective>Audit existing test quality and produce QA_AUDIT_REPORT.md. If Playwright MCP is connected, verify E2E test locators against the live DOM via browser_navigate + browser_snapshot.</objective>
-    <execution_context>@agents/qaa-validator.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: audit
-    app_url: {auto-detect from test config baseURL, or ask user}
-    </parameters>
-  "
-)
-
-3. Present audit results and wait for user approval.
-4. Invoke executor agent to apply approved improvements:
-
-Task(
-  prompt="
-    <objective>Apply approved improvements to existing tests without deleting working tests. If Playwright MCP is connected, use browser_navigate + browser_snapshot to extract real locators when upgrading from Tier 4 to Tier 1.</objective>
-    <execution_context>@agents/qaa-executor.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .qa-output/QA_AUDIT_REPORT.md
-    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: update
-    app_url: {auto-detect from test config baseURL, or ask user}
-    </parameters>
-  "
-)
-
-**Update scopes:**
-- `fix` — repair broken tests only
-- `improve` — upgrade locators, assertions, POM structure
-- `add` — add missing test cases without modifying existing
-- `full` — audit everything, then improve with approval (default)
-
-**Rule:** NEVER delete or rewrite working tests without user approval. Surgical: add, fix, improve — never replace.
-
----
-
-### POM ONLY MODE (`--pom-only`)
-
-Generate only Page Object Model files — no test specs.
-
-1. Read `CLAUDE.md` — POM rules, locator tier hierarchy, naming conventions.
-2. Invoke executor agent in POM-only mode:
-
-Task(
-  prompt="
-    <objective>Generate Page Object Models following CLAUDE.md POM rules. If Playwright MCP is connected and an app URL is available, navigate each page first to extract real locators (data-testid, ARIA roles, labels) from the live DOM via browser_navigate + browser_snapshot before generating POMs. This ensures POM locators match the real app instead of guessing from source code.</objective>
-    <execution_context>@agents/qaa-executor.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
-    </files_to_read>
-    <parameters>
-    user_input: $ARGUMENTS
-    mode: pom-only
-    app_url: {auto-detect from test config baseURL, or ask user}
-    </parameters>
-  "
-)
-
-**Produces:**
-- BasePage file (if not already present)
-- Feature-specific POM files following `[PageName]Page.[ext]` naming convention
-- No test specs, no fixtures
-
-**POM rules enforced:**
-- One class per page — no god objects
-- No assertions in page objects — assertions belong ONLY in test specs
-- Locators as readonly properties — Tier 1 preferred (data-testid, ARIA roles)
-- Actions return void or next page — for fluent chaining
-- State queries return data — let the test decide what to assert
-- Every POM extends BasePage
-
-$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 "=== CHECKLIST START ==="
-echo "1. Locator Registry:"
-ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
-echo "2. MY_PREFERENCES.md:"
-cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
-echo "3. Generated test files:"
-find tests/ pages/ fixtures/ -type f 2>/dev/null | head -20 || echo "NO_TEST_FILES_FOUND"
-echo "4. MCP evidence (if browser was used):"
-ls .qa-output/mcp-evidence/ 2>/dev/null || echo "NO_MCP_EVIDENCE"
-echo "=== 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_LOCATORS when MCP was used, NO_TEST_FILES after generation), 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.
+# QA Create Test
+
+Create, update, or generate tests from tickets — all in one command. Supports six modes: generate tests from code analysis, generate tests from a live app URL (from-aut), generate tests from a ticket (Jira/Linear/GitHub), create Test Cases in Azure DevOps from a work item, update/improve existing tests, or generate POM files only. Uses Playwright MCP to extract real locators from the live app when available.
+
+
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps.
+
+1. FIRST tool call: run the intent detector with `$ARGUMENTS` passed LITERALLY
+   (the actual command lives in the "## Intent Detection" section below).
+2. Print the INPUT DETECTION banner (exact output from intent-detector.cjs).
+3. Determine `ALL_FROM_FLAGS`. If interactive (`IS_AUTO=false`) AND any value
+   came from NL/default (`ALL_FROM_FLAGS=false`), PAUSE for yes/no confirmation.
+   Do NOT proceed without it.
+   ```bash
+   ALL_FROM_FLAGS=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); const sources=Object.values(j.resolved).map(v=>v.source); console.log(sources.length>0 && sources.every(s=>s==='flag') ? 'true' : 'false')")
+   ```
+   Pause prompt (when applicable):
+   ```
+   The values above were resolved from natural language and/or defaults.
+   Do you want to continue with these inputs? (yes/no)
+   ```
+4. Determine MODE using the "Mode Detection Logic" section below
+   (pom-only → ado → from-ticket → from-aut → update → from-code). Use the
+   detector's `intent.suggested_mode` as the heuristic — do NOT decide the mode
+   by your own NL parsing.
+5. Print the mode banner (Step 1 of Instructions) and execute that mode's flow
+   IN ORDER, including its own approval gates (e.g. update mode presents the
+   audit and waits for approval). Modes that generate files spawn the
+   qaa-executor (or mode-specific) sub-agent — do NOT hand-write test files
+   inline instead of the sub-agent.
+
+### DO NOT
+- Skip the INPUT DETECTION banner or the mode banner
+- Run AskUserQuestion or any tool before the intent detector
+- Use AskUserQuestion in place of the yes/no confirmation pause — use the exact text prompt above
+- Decide the mode by parsing NL in your own head — use the detector + Mode Detection Logic
+- Generate or overwrite any test files before the inputs are confirmed (step 3)
+- Hand-write test files inline instead of spawning the sub-agent the mode specifies
+- Delete or rewrite working tests without user approval (update mode is surgical: add / fix / improve, never replace)
+- Assume context, app URL, framework, ticket, or any value from previous command
+  invocations (/qa-start, prior /qa-create-test calls, etc.). Each invocation is
+  self-contained — the detector returns defaults precisely because the user did
+  not pass them.
+- Invent steps not in this command, or reorder the ones that are
+
+If you find yourself improvising, deciding the mode before the detector runs,
+generating files before confirmation, or asking questions out of order — STOP
+and restart from step 1.
+
+### Pass user input literally to the intent detector
+
+When you run the intent detector with `$ARGUMENTS`, substitute that placeholder
+with the RAW user input as received, NOT a pre-translated flag string. If you
+pre-translate, the detector reports every value as `source: flag`, sets
+`ALL_FROM_FLAGS=true`, and bypasses the confirmation checkpoint.
+
+
+## Usage
+
+```
+/qa-create-test <feature-or-source> [options]
+```
+
+### Modes (auto-detected from arguments)
+
+| Mode | Trigger | Example |
+|------|---------|---------|
+| **From code** | Feature name (no URL, no path to tests) | `/qa-create-test login` |
+| **From ticket** | URL, shorthand (#123), or `--ticket` flag | `/qa-create-test https://github.com/org/repo/issues/42` |
+| **From AUT** | Non-ticket URL or `--app-url` (explore live app) | `/qa-create-test signup on https://staging.example.com` |
+| **Azure DevOps** | `--ado` flag with work item ID or ADO URL | `/qa-create-test --ado 85508` |
+| **Update existing** | Path to existing test files or `--update` flag | `/qa-create-test --update tests/e2e/` |
+| **POM only** | `--pom-only` flag | `/qa-create-test --pom-only src/pages/` |
+
+### Options
+
+- `--dev-repo <path>` — path to developer repository (default: current directory)
+- `--app-url <url>` — URL of running application for E2E execution and locator extraction (auto-detects if not provided)
+- `--skip-run` — skip E2E execution, only generate and statically validate
+- `--ticket <source>` — force ticket mode with: URL, shorthand (#123, org/repo#123), file path, or plain text
+- `--update <path>` — force update mode: audit and improve existing tests at path
+- `--scope fix|improve|add|full` — for update mode only (default: full)
+- `--ado <work-item-id>` — Azure DevOps mode: read a work item and create Test Cases in ADO (accepts ID or full ADO URL)
+- `--area-path <path>` — (ADO mode) override area path for created test cases (default: source work item's area path)
+- `--iteration-path <path>` — (ADO mode) override iteration path for created test cases (default: source work item's iteration path)
+- `--skip-dedup` — (ADO mode) skip deduplication check against existing linked test cases
+- `--pom-only [path]` — generate only Page Object Model files (BasePage + feature POMs), no test specs
+- `--framework <name>` — override framework auto-detection (playwright, cypress, selenium) — used with --pom-only
+
+### Mode Detection Logic
+
+```
+if --pom-only:
+  MODE = "pom-only"
+elif --ado flag OR argument matches ADO URL (dev.azure.com, *.visualstudio.com):
+  MODE = "ado"
+elif argument matches ticket URL pattern (github.com, atlassian.net, linear.app) OR contains "#" + digits OR --ticket flag:
+  MODE = "from-ticket"
+elif argument matches URL pattern (https?://) AND NOT a ticket platform:
+  MODE = "from-aut"             # NEW: lightweight URL → tests, single-shot
+elif --update flag OR argument is path to existing test directory/files:
+  MODE = "update"
+else:
+  MODE = "from-code"
+```
+
+**Mode detection uses `bin/lib/intent-detector.cjs`** for robust URL/path/framework parsing. The detector already classifies URLs as ticket vs AUT, so the workflow can branch cleanly between `from-ticket` and `from-aut` modes.
+
+## What It Produces
+
+### From Code Mode
+- Test spec files (unit, API, E2E as appropriate)
+- Page Object Model files (for E2E tests)
+- Fixture files (test data)
+- Locator registry entries (`.qa-output/locators/`)
+- E2E_RUN_REPORT.md (if E2E tests ran against live app)
+
+### From Ticket Mode
+- TEST_CASES_FROM_TICKET.md — traceability matrix (AC → test case)
+- GENERATION_PLAN_TICKET.md — synthetic generation plan
+- Test spec files with `traces_to` fields linking back to ticket ACs
+- VALIDATION_REPORT.md
+
+### Azure DevOps Mode
+- Test Cases created directly in Azure DevOps (via `testplan_create_test_case`)
+- Test Cases linked to source work item via *Tested By* relationship
+- Tags applied: `Smoke`, `Regression`, `Critical`, `AutomationCandidate`, `NeedsReview`
+- `ai-tasks/ticket-{id}/test-cases.md` — structured report
+- Report attached to work item (if `ADO_MCP_AUTH_TOKEN` is set) or written to `Custom.QATestCasesReport` field (fallback)
+
+### From AUT Mode
+
+- Test spec files generated directly from URL exploration (no full pipeline)
+- Page Object Model files for the discovered pages
+- Locator registry entries from real DOM (via Playwright MCP)
+- VALIDATION_REPORT.md
+- No PR created — local delivery only
+
+The agent navigates the URL with Playwright MCP, discovers interactive elements, and generates tests targeting them. Skips codebase-map check, scan, and analyze stages. **Faster than `/qa-start --app-url`** when you only need tests for one specific URL.
+
+### Update Mode
+- QA_AUDIT_REPORT.md — current quality assessment
+- Improved test files (after user approval)
+
+
+## Intent Detection
+
+Before processing arguments, run the intent detector to support natural-language input alongside flags. Flags always win over NL.
+
+```bash
+RESOLVED=$(node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" --aliases '{"app_url":"app-url","framework":"framework","ticket":"ticket","ado":"ado","update":"update","pom_only":"pom-only","skip_map":"skip-map","skip_run":"skip-run"}')
+
+# Print INPUT DETECTION banner (always shown, even if defaults are used)
+echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.banner)"
+
+# Extract resolved values
+APP_URL=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.app_url?.value || '')")
+FRAMEWORK=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.framework?.value || '')")
+TICKET=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.ticket?.value || '')")
+SUGGESTED_MODE=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.intent.suggested_mode || '')")
+```
+
+The detector resolves the mode automatically when possible (from-ticket, from-aut, ado, etc.) and surfaces it in `SUGGESTED_MODE`. The mode detection logic in Step 1 below uses these resolved values.
+
+## Instructions
+
+### Step 1: Detect Mode
+
+Parse `$ARGUMENTS` to determine mode using the detection logic above.
+
+Print mode banner:
+```
+=== QA Create Test ===
+Mode: {from-code | from-aut | from-ticket | ado | update | pom-only}
+Target: {feature name | ticket URL | ADO work item ID | test path}
+App URL: {url or "auto-detect"}
+===========================
+```
+
+---
+
+### FROM CODE MODE
+
+1. Read `CLAUDE.md` — POM rules, locator tiers, assertion rules, naming conventions, quality gates.
+1b. Read `~/.claude/qaa/MY_PREFERENCES.md` if it exists — user's personal QA preferences override CLAUDE.md defaults when there is a conflict.
+2. Read existing analysis artifacts if available:
+   - `.qa-output/QA_ANALYSIS.md` — architecture context
+   - `.qa-output/TEST_INVENTORY.md` — pre-defined test cases for this feature
+3. **Check for codebase map** (`.qa-output/codebase/`):
+   - Look for: `CODE_PATTERNS.md`, `API_CONTRACTS.md`, `TEST_SURFACE.md`, `TESTABILITY.md`
+   - If at least 2 of these files exist: read them all for project context (naming conventions, API shapes, testable surfaces).
+   - **If NONE of these files exist: STOP and tell the user:**
+     ```
+     ⚠ No codebase map found (.qa-output/codebase/ is empty or missing).
+
+     The codebase map provides critical context: naming conventions, API contracts,
+     testable surfaces, and project structure. Without it, generated tests will lack
+     project-specific context and may not follow your repo's conventions.
+
+     Run /qa-map first to generate the codebase map, then re-run /qa-create-test.
+
+     To skip this check and proceed without context: re-run with --skip-map
+     ```
+     Only proceed without codebase map if the user explicitly passes `--skip-map`.
+
+4. **Check existing locator registry and extract new locators from live app:**
+
+   a. Read `.qa-output/locators/LOCATOR_REGISTRY.md` if it exists.
+
+   b. If locators for this feature already exist in the registry AND no `--app-url` was provided: reuse cached locators.
+
+   c. If locators are missing or `--app-url` was provided: Use Playwright MCP to navigate the app and extract real locators:
+      ```
+      mcp__playwright__browser_navigate({ url: "{app_url}/{feature_path}" })
+      mcp__playwright__browser_snapshot()
+      ```
+      Extract all data-testid, ARIA roles, labels, placeholders.
+      Navigate through multi-page flows if needed.
+      Write per-feature locator file to `.qa-output/locators/{feature}.locators.md`.
+      Update the registry `.qa-output/locators/LOCATOR_REGISTRY.md`.
+
+   If no app URL available and no locators in registry, skip — executor proposes locators from source code.
+
+5. Invoke executor agent to generate test files:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-executor.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-executor.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <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>~/.claude/qaa/agents/qaa-executor.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/locators/{feature}.locators.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/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
+    mode: feature-test
+    codebase_map_dir: .qa-output/codebase
+    locator_registry: .qa-output/locators/LOCATOR_REGISTRY.md
+    </parameters>
+  "
+)
+
+6. If E2E test files were generated AND `--skip-run` was NOT passed, invoke E2E runner:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-e2e-runner.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-e2e-runner.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <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>~/.claude/qaa/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>
+    <parameters>
+    app_url: {from --app-url flag or auto-detect}
+    output_dir: .qa-output
+    </parameters>
+  "
+)
+
+7. Present results with file counts and suggest `/qa-pr`.
+
+---
+
+### FROM AUT MODE
+
+Generate tests directly from a running application URL — no ticket, no spec, no full pipeline. Triggered when an AUT URL (non-ticket) is resolved (or `--app-url` in NL) and no other mode applies. Faster than `/qa-start --app-url` when you only need tests for one specific flow. **No PR is created — local delivery only.**
+
+**Production-URL safety (read first):** if the AUT is a live/production site, exploration AND generated tests MUST be read-only. NEVER submit forms, create accounts/records, post data, or trigger destructive mutations against production. For flows that open a modal/form, assert on its presence/contents then CANCEL — never submit. Reserve any state-changing path for validation-failure assertions only. Never hardcode credentials.
+
+1. Read `CLAUDE.md` (POM rules, locator tiers, assertion rules, naming, quality gates) and `~/.claude/qaa/MY_PREFERENCES.md` if it exists.
+
+2. **Match existing conventions.** If a test repo already exists (cypress/, tests/, page-objects/, etc.), read 2-3 existing specs + the POM base + the selectors/fixtures registry so generated tests match the project's structure, naming, and locator style. Do NOT invent a parallel structure.
+
+3. **Explore the app with Playwright MCP.** For each route/flow in the request:
+   ```
+   mcp__playwright__browser_navigate({ url: "{app_url}{route}" })
+   mcp__playwright__browser_snapshot()
+   ```
+   Discover interactive elements and real locators (data-testid, ARIA roles, labels, placeholders) and the ACTUAL behavior. Reconcile the request against reality: if the live DOM contradicts the user's description (e.g. a button isn't rendered for anonymous users), record the discrepancy — do NOT generate a test that asserts behavior the app does not exhibit. Persist verified locators to `.qa-output/locators/{feature}.locators.md` and update `.qa-output/locators/LOCATOR_REGISTRY.md`.
+
+4. **Auth handling.** If a flow requires authentication: if `TEST_USER_*` creds are configured (cypress.env.json / env vars), use the project's login command (e.g. `cy.loginAs()`); otherwise generate the authenticated specs but guard them to skip cleanly (e.g. `cy.skipIfNoTestAccount()`) and tell the user they need creds to run them.
+
+5. **CHECKPOINT — present the test plan and WAIT for approval.** Before writing ANY file, present the inferred plan and pause:
+   ```
+   === FROM-AUT TEST PLAN ===
+   App:       {app_url}
+   Flow:      {what was requested}
+   Framework: {detected}
+   Proposed test cases:
+     1. [ID] [priority] {title} — {concrete assertion(s)}   (locators: tier {N})
+     2. ...
+   Discrepancies vs request: {list, or "none"}
+   Files to create: {spec paths, POM paths, fixtures}
+   Auth: {creds available → live | no creds → generated-but-skipped}
+   ==========================
+   Proceed with generation? (yes / modify / cancel)
+   ```
+   Do NOT generate files until the user approves. On "modify" → adjust and re-present. On "cancel" → stop and deliver only the plan. (This gate is mandatory — from-aut writes specs against a live app; never generate a batch without approval.)
+
+6. After approval, invoke the executor to generate specs + POMs + fixtures:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-executor.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-executor.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Generate the approved from-aut test cases following CLAUDE.md standards and the existing repo conventions, using the verified locators from the registry. Read-only against production — never generate a spec that submits/creates data. Query Context7 MCP to verify framework syntax before generating code.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/locators/LOCATOR_REGISTRY.md
+    - .qa-output/locators/{feature}.locators.md
+    - .qa-output/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - {2-3 existing spec files + the POM base, to match conventions}
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: from-aut
+    app_url: {resolved app_url}
+    approved_plan: {the test cases the user approved in step 5}
+    locator_registry: .qa-output/locators/LOCATOR_REGISTRY.md
+    </parameters>
+  "
+)
+
+7. If E2E specs were generated AND `--skip-run` was NOT passed AND an app URL is available, invoke the e2e-runner (same Task() spawn as FROM CODE MODE step 6). Honor the production-safety rule — read-only flows only.
+
+8. Present results (file counts, locator tiers, any discrepancies surfaced in step 3), then suggest `/qa-pr`. No PR is created in this mode — local delivery only.
+
+---
+
+### FROM TICKET MODE
+
+1. Read `CLAUDE.md` — all QA standards.
+2. Execute the ticket workflow end-to-end:
+
+Follow the workflow defined in `@workflows/qa-from-ticket.md` end-to-end.
+Preserve all workflow gates (ticket parsing, acceptance criteria extraction, traceability matrix, validation).
+
+Key steps in the workflow:
+- Parse ticket source (GitHub URL, Jira URL, Linear URL, file, or plain text)
+- Fetch ticket content (via `gh issue view`, WebFetch, or file read)
+- Extract acceptance criteria, user stories, edge cases
+- Scan dev repo for related source files
+- Extract locators from live app via Playwright MCP (if app URL available)
+- Generate test cases with traceability matrix (every AC maps to ≥1 test case)
+- Spawn executor agent to produce test files
+- Spawn validator agent for 4-layer validation
+- Print summary with AC coverage and traceability
+
+**Traceability guarantee:** Every acceptance criterion maps to at least one test case via the `traces_to` field.
+
+**Supported ticket sources:**
+
+| Format | Example | Detection |
+|--------|---------|-----------|
+| GitHub Issue URL | `https://github.com/org/repo/issues/123` | Contains `github.com` + `/issues/` |
+| GitHub shorthand | `org/repo#123` or `#123` | Contains `#` + digits |
+| Jira URL | `https://company.atlassian.net/browse/PROJ-123` | Contains `.atlassian.net/browse/` |
+| Linear URL | `https://linear.app/team/issue/TEAM-123` | Contains `linear.app` |
+| File path | `./tickets/feature-spec.md` | Path exists on disk |
+| Plain text | `"As a user I want to..."` | None of the above match |
+
+---
+
+### ADO MODE (Azure DevOps)
+
+Create Test Cases directly in Azure DevOps from a work item. Reads the work item content (repro steps, acceptance criteria, comments, attachments), designs test cases with boundary detection and deduplication, and creates them in ADO with full traceability.
+
+**Prerequisites:** ADO MCP server must be connected (provides `wit_get_work_item`, `testplan_create_test_case`, etc.).
+
+Execute the full ADO workflow defined in `@commands/qa-create-test-ado.md`:
+
+1. **Phase 1** — Read pipeline context: CLAUDE.md, MY_PREFERENCES.md, codebase map, locator registry
+2. **Phase 2** — Retrieve work item with relations, comments, and attachments
+3. **Phase 2b** — Deduplication check against existing linked test cases (skip with `--skip-dedup`)
+4. **Phase 3** — Extract test source content based on work item type (Bug → Repro Steps, User Story → Acceptance Criteria)
+5. **Phase 4** — Design test cases with boundary value detection, tagging rules, confidence scoring, and preconditions
+6. **Phase 5** — Create test cases in ADO via `testplan_create_test_case`, link via *Tested By*, set tags
+7. **Phase 6** — Generate structured report to `ai-tasks/ticket-{id}/test-cases.md`
+8. **Phase 7** — Attach report to source work item
+
+**Key features:**
+- Boundary value triplets: detects `max`, `min`, `limit`, `threshold` keywords with numeric values → generates N-1, N, N+1 test cases
+- Deduplication: checks existing linked TCs before creating, prevents duplicates
+- Confidence scoring: `Specified` (explicit source) vs `Draft` (inferred, tagged `NeedsReview`)
+- Cross-references codebase map for project-specific context when available
+- Supports `--area-path` and `--iteration-path` overrides
+
+For the complete step-by-step process, see `@commands/qa-create-test-ado.md`.
+
+---
+
+### UPDATE MODE
+
+1. Read `CLAUDE.md` — quality gates, locator tiers, assertion rules, POM rules.
+2. Invoke validator agent in audit mode:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-validator.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-validator.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Audit existing test quality and produce QA_AUDIT_REPORT.md. If Playwright MCP is connected, verify E2E test locators against the live DOM via browser_navigate + browser_snapshot.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-validator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: audit
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+3. Present audit results and wait for user approval.
+4. Invoke executor agent to apply approved improvements:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-executor.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-executor.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Apply approved improvements to existing tests without deleting working tests. If Playwright MCP is connected, use browser_navigate + browser_snapshot to extract real locators when upgrading from Tier 4 to Tier 1.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/QA_AUDIT_REPORT.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: update
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+**Update scopes:**
+- `fix` — repair broken tests only
+- `improve` — upgrade locators, assertions, POM structure
+- `add` — add missing test cases without modifying existing
+- `full` — audit everything, then improve with approval (default)
+
+**Rule:** NEVER delete or rewrite working tests without user approval. Surgical: add, fix, improve — never replace.
+
+---
+
+### POM ONLY MODE (`--pom-only`)
+
+Generate only Page Object Model files — no test specs.
+
+1. Read `CLAUDE.md` — POM rules, locator tier hierarchy, naming conventions.
+2. Invoke executor agent in POM-only mode:
+
+Task(
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-executor.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-executor.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
+    <objective>Generate Page Object Models following CLAUDE.md POM rules. If Playwright MCP is connected and an app URL is available, navigate each page first to extract real locators (data-testid, ARIA roles, labels) from the live DOM via browser_navigate + browser_snapshot before generating POMs. This ensures POM locators match the real app instead of guessing from source code.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-executor.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists)
+    </files_to_read>
+    <parameters>
+    user_input: $ARGUMENTS
+    mode: pom-only
+    app_url: {auto-detect from test config baseURL, or ask user}
+    </parameters>
+  "
+)
+
+**Produces:**
+- BasePage file (if not already present)
+- Feature-specific POM files following `[PageName]Page.[ext]` naming convention
+- No test specs, no fixtures
+
+**POM rules enforced:**
+- One class per page — no god objects
+- No assertions in page objects — assertions belong ONLY in test specs
+- Locators as readonly properties — Tier 1 preferred (data-testid, ARIA roles)
+- Actions return void or next page — for fluent chaining
+- State queries return data — let the test decide what to assert
+- Every POM extends BasePage
+
+$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 "=== CHECKLIST START ==="
+echo "1. Locator Registry:"
+ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
+echo "2. MY_PREFERENCES.md:"
+cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
+echo "3. Generated test files:"
+find tests/ pages/ fixtures/ -type f 2>/dev/null | head -20 || echo "NO_TEST_FILES_FOUND"
+echo "4. MCP evidence (if browser was used):"
+ls .qa-output/mcp-evidence/ 2>/dev/null || echo "NO_MCP_EVIDENCE"
+echo "=== 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_LOCATORS when MCP was used, NO_TEST_FILES after generation), 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.