qaa-agent 1.7.4 → 1.8.1

package/agents/qaa-planner.md

@@ -1,3 +1,10 @@
+---
+name: qaa-planner
+description: Produces structured generation plan from test inventory
+skills:
+  - qa-template-engine
+---
+
 <purpose>
 Read TEST_INVENTORY.md and QA_ANALYSIS.md to produce a structured generation plan that maps every test case to an output file, grouped by feature domain with explicit task dependencies. This agent is the bridge between "what tests are needed" (from the analyzer) and "tests exist on disk" (from the executor). It is spawned by the orchestrator after the analyzer completes successfully via Task(subagent_type='qaa-planner'). The planner does NOT produce test files -- it produces a plan that the executor consumes. The generation plan is an internal artifact with no template; the planner defines its own output format documented in the <output> section below.
 </purpose>
@@ -403,3 +410,37 @@ The planner agent has completed successfully when:
 8. Return values provided to orchestrator: file_path, total_tasks, total_files, feature_count, dependency_depth, test_case_count, commit_hash
 9. All quality gate checks pass
 </success_criteria>
+
+## 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 "=== PLANNER CHECKLIST START ==="
+echo "1. Primary inputs:"
+ls .qa-output/TEST_INVENTORY.md .qa-output/QA_ANALYSIS.md 2>/dev/null || echo "INPUTS_NOT_FOUND"
+echo "2. Test case count from inventory:"
+grep -cE "^\| (UT|INT|API|E2E)-" .qa-output/TEST_INVENTORY.md 2>/dev/null || echo "NO_TEST_CASES_COUNTED"
+echo "3. Architecture overview from QA_ANALYSIS:"
+grep -E "^### |system_type|framework|language" .qa-output/QA_ANALYSIS.md 2>/dev/null | head -15 || echo "NO_ARCHITECTURE_OVERVIEW"
+echo "4. Pyramid percentages:"
+grep -E "Unit [0-9]+%|Integration [0-9]+%|API [0-9]+%|E2E [0-9]+%" .qa-output/QA_ANALYSIS.md 2>/dev/null || echo "NO_PYRAMID_PERCENTAGES"
+echo "5. Codebase map documents:"
+ls .qa-output/codebase/ 2>/dev/null || echo "NO_CODEBASE_MAP"
+echo "6. TESTABILITY.md mock complexity:"
+grep -E "pure function|stateful" .qa-output/codebase/TESTABILITY.md 2>/dev/null | head -10 || echo "NO_TESTABILITY"
+echo "7. Locator Registry:"
+ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
+echo "8. Generation plan output:"
+ls .qa-output/GENERATION_PLAN.md 2>/dev/null || echo "PLAN_NOT_WRITTEN"
+echo "9. MY_PREFERENCES.md:"
+cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
+echo "=== PLANNER 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 (INPUTS_NOT_FOUND, PLAN_NOT_WRITTEN), fix it before returning.
+- If output shows expected "not found" results (e.g., NO_CODEBASE_MAP when mapper hasn't run), that is fine — the point is you RAN the command instead of assuming the answer.
+- Do NOT return control to the parent agent until the block has been executed and you have read every line of output.
+

package/agents/qaa-testid-injector.md

@@ -1,3 +1,10 @@
+---
+name: qaa-testid-injector
+description: Scans and injects data-testid attributes in frontend components
+skills:
+  - qa-testid-injector
+---
+
 <purpose>
 Scan frontend component files in a developer repository, audit every interactive UI element for `data-testid` coverage, and inject missing `data-testid` attributes following the `{context}-{description}-{element-type}` naming convention. Reads SCAN_MANIFEST.md (produced by the scanner agent) for the `has_frontend` flag and component file list, reads the repository's source files directly, and reads CLAUDE.md for the data-testid Convention section. Produces TESTID_AUDIT_REPORT.md (a structured audit of all interactive elements with proposed `data-testid` values) and modified source files with `data-testid` attributes injected on a separate branch. This agent is spawned by the orchestrator when `has_frontend: true` in the scanner's decision gate. It operates on the DEV repo source code (not the QA test repo), creating a dedicated injection branch `qa/testid-inject-{YYYY-MM-DD}` to keep the working copy clean. The user merges the injection branch if approved.
 </purpose>
@@ -601,6 +608,25 @@ INJECTOR_SKIPPED:
 ```
 </output>
 
+## Non-negotiable rules
+
+These rules are hardcoded in the agent body because they MUST NOT be skipped under any circumstance, regardless of whether the skill is loaded or not.
+
+### Playwright MCP usage is mandatory when app_url is provided
+
+When an `app_url` is available in the orchestrator prompt (or provided via `--app-url` flag), live DOM verification via Playwright MCP is **required, not optional**. Source-only scans miss dynamically rendered elements, conditionally shown components, and third-party injections.
+
+1. **If `app_url` is available, the agent MUST call Playwright MCP tools** — at minimum `mcp__playwright__browser_navigate` (once per unique route from SCAN_MANIFEST.md) and `mcp__playwright__browser_snapshot` (once per navigated route). If MCP tools are unavailable, halt with `ENVIRONMENT_ISSUE: Playwright MCP not connected` instead of falling back to source-only.
+2. **Skipping MCP verification is only permitted when `app_url` is not provided**, and this skip MUST be explicitly recorded in TESTID_AUDIT_REPORT.md under a "Live DOM Verification" section with reason "no app_url provided".
+3. **Persist evidence of MCP usage** to `.qa-output/mcp-evidence/qaa-testid-injector-session.md` with:
+   - `session_start: {ISO timestamp}` and `session_end: {ISO timestamp}`
+   - `app_url:` base URL provided
+   - `routes_navigated:` list of every route passed to `browser_navigate`
+   - `snapshots_taken:` count + route per snapshot
+   - `dynamic_elements_found:` count of elements present in DOM but absent from source scan (these trigger extra injections)
+   - `browser_closed: true`
+4. **If app_url is provided but the evidence file is missing or lists zero navigations, the audit is INVALID** — TESTID_AUDIT_REPORT.md must not be produced and the agent must return a hard failure.
+
 <quality_gate>
 Before considering this agent's work complete, verify ALL of the following.
 
@@ -641,3 +667,45 @@ The testid-injector agent has completed successfully when:
 9. Structured return values provided to orchestrator: report_path, changelog_path, branch name, coverage scores (before/after), element counts, validation status, commit hash
 10. All quality gate checks pass (8 template items + 6 injector-specific items)
 </success_criteria>
+
+## 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 "=== TESTID-INJECTOR CHECKLIST START ==="
+echo "1. SCAN_MANIFEST.md (input):"
+ls .qa-output/SCAN_MANIFEST.md 2>/dev/null || echo "SCAN_MANIFEST_NOT_FOUND"
+echo "2. Frontend detection in manifest:"
+grep -E "has_frontend|component_patterns|frontend" .qa-output/SCAN_MANIFEST.md 2>/dev/null | head -10 || echo "NO_FRONTEND_DETECTION"
+echo "3. Component file count:"
+grep -cE "\.(tsx|jsx|vue|svelte|html)$" .qa-output/SCAN_MANIFEST.md 2>/dev/null || echo "NO_COMPONENT_FILES"
+echo "4. Codebase map documents:"
+ls .qa-output/codebase/ 2>/dev/null || echo "NO_CODEBASE_MAP"
+echo "5. CODE_PATTERNS.md interactive elements:"
+grep -E "interactive|button|input|form" .qa-output/codebase/CODE_PATTERNS.md 2>/dev/null | head -10 || echo "NO_CODE_PATTERNS"
+echo "6. Locator Registry:"
+ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
+echo "7. Output artifacts:"
+ls .qa-output/TESTID_AUDIT_REPORT.md .qa-output/INJECTION_CHANGELOG.md 2>/dev/null || echo "OUTPUTS_NOT_WRITTEN"
+echo "8. Coverage score in report:"
+grep -E "Coverage Score|[0-9]+/[0-9]+" .qa-output/TESTID_AUDIT_REPORT.md 2>/dev/null | head -5 || echo "NO_COVERAGE_SCORE"
+echo "9. MY_PREFERENCES.md:"
+cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
+echo "10. MCP evidence file:"
+ls .qa-output/mcp-evidence/qaa-testid-injector-session.md 2>/dev/null || echo "NO_MCP_EVIDENCE"
+echo "11. MCP session boundaries:"
+grep -E "session_start:|routes_navigated:|browser_closed: true" .qa-output/mcp-evidence/qaa-testid-injector-session.md 2>/dev/null || echo "NO_MCP_SESSION"
+echo "12. Routes navigated via MCP:"
+grep -cE "^  - http|^  - /" .qa-output/mcp-evidence/qaa-testid-injector-session.md 2>/dev/null || echo "NO_ROUTES_NAVIGATED"
+echo "13. MCP skip documentation:"
+grep -E "Live DOM Verification|no app_url" .qa-output/TESTID_AUDIT_REPORT.md 2>/dev/null || echo "NO_MCP_SKIP_DOCUMENTED"
+echo "=== TESTID-INJECTOR 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 (SCAN_MANIFEST_NOT_FOUND, OUTPUTS_NOT_WRITTEN), fix it before returning.
+- If output shows expected "not found" results (e.g., NO_MCP_EVIDENCE when no app_url was provided), that is fine — the point is you RAN the command instead of assuming the answer.
+- Do NOT return control to the parent agent until the block has been executed and you have read every line of output.
+

package/agents/qaa-validator.md

@@ -1,3 +1,10 @@
+---
+name: qaa-validator
+description: Validates generated test code across 4 layers with fix loops
+skills:
+  - qa-self-validator
+---
+
 <purpose>
 Validate generated test code across 4 layers (Syntax, Structure, Dependencies, Logic) and auto-fix issues with a closed-loop fix protocol. Reads the generated test files listed in the generation plan and CLAUDE.md quality standards. Produces VALIDATION_REPORT.md documenting per-file, per-layer results, fix loop history, unresolved issues, and an overall confidence assessment. Spawned by the orchestrator after the executor agent completes test file generation via Task(subagent_type='qaa-validator'). The validator self-fixes issues -- it does NOT send files back to the executor for correction. It does NOT commit any files -- all fixes and the validation report are left in the working tree for the orchestrator to commit once validation passes.
 </purpose>
@@ -488,3 +495,43 @@ The validator agent has completed successfully when:
 6. Return values provided to orchestrator: report_path, overall_status, confidence, layers_summary, fix_loops_used, issues_found, issues_fixed, unresolved_count
 7. All quality gate checks pass (7 template items + 6 validator-specific items)
 </success_criteria>
+
+## 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 "=== VALIDATOR CHECKLIST START ==="
+echo "1. Validation report:"
+ls .qa-output/VALIDATION_REPORT.md 2>/dev/null || echo "REPORT_NOT_WRITTEN"
+echo "2. Required sections in report:"
+grep -E "^## " .qa-output/VALIDATION_REPORT.md 2>/dev/null || echo "NO_SECTIONS_FOUND"
+echo "3. Confidence level:"
+grep -E "HIGH|MEDIUM|LOW" .qa-output/VALIDATION_REPORT.md 2>/dev/null | head -5 || echo "NO_CONFIDENCE_LEVEL"
+echo "4. Last commit (validator must NOT commit):"
+git log --oneline -1 2>/dev/null || echo "NO_GIT_HISTORY"
+echo "5. Modified files in working tree:"
+git status 2>/dev/null | grep "modified:" || echo "NO_MODIFIED_FILES"
+echo "6. MY_PREFERENCES.md:"
+cat ~/.claude/qaa/MY_PREFERENCES.md 2>/dev/null || echo "FILE_NOT_FOUND"
+echo "7. Fix loop iterations:"
+grep -c "Loop" .qa-output/VALIDATION_REPORT.md 2>/dev/null || echo "NO_FIX_LOOPS"
+echo "8. Generation plan (input):"
+ls .qa-output/GENERATION_PLAN.md 2>/dev/null || echo "NO_GENERATION_PLAN"
+echo "9. Plan tasks parsed:"
+grep -cE "files_to_create|task_id" .qa-output/GENERATION_PLAN.md 2>/dev/null || echo "NO_PLAN_TASKS"
+echo "10. Locator Registry:"
+ls .qa-output/locators/ 2>/dev/null || echo "NO_LOCATORS_FOUND"
+echo "11. Four validation layers per file:"
+grep -E "Syntax|Structure|Dependencies|Logic" .qa-output/VALIDATION_REPORT.md 2>/dev/null | head -20 || echo "NO_VALIDATION_LAYERS"
+echo "12. TEST_INVENTORY (input):"
+ls .qa-output/TEST_INVENTORY.md 2>/dev/null || echo "NO_TEST_INVENTORY"
+echo "=== VALIDATOR 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 (REPORT_NOT_WRITTEN, NO_VALIDATION_LAYERS), fix it before returning.
+- If output shows expected "not found" results (e.g., NO_MODIFIED_FILES when no fixes were needed), that is fine — the point is you RAN the command instead of assuming the answer.
+- Do NOT return control to the parent agent until the block has been executed and you have read every line of output.
+