qaa-agent 1.9.5 → 1.9.6

package/commands/qa-create-test.md

@@ -227,6 +227,7 @@ App URL: {url or "auto-detect"}
 5. Invoke executor agent to generate test files:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -280,6 +281,7 @@ Task(
 6. If E2E test files were generated AND `--skip-run` was NOT passed, invoke E2E runner:
 
 Task(
+  subagent_type="qaa-e2e-runner",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -366,6 +368,7 @@ Generate tests directly from a running application URL — no ticket, no spec, n
 6. After approval, invoke the executor to generate specs + POMs + fixtures:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -485,6 +488,7 @@ For the complete step-by-step process, see `@commands/qa-create-test-ado.md`.
 2. Invoke validator agent in audit mode:
 
 Task(
+  subagent_type="qaa-validator",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -528,6 +532,7 @@ Task(
 4. Invoke executor agent to apply approved improvements:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -587,6 +592,7 @@ Generate only Page Object Model files — no test specs.
 2. Invoke executor agent in POM-only mode:
 
 Task(
+  subagent_type="qaa-executor",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-fix.md

@@ -396,9 +396,9 @@ The validator runs 4 layers per file:
 3. **Dependencies** — all imports resolve
 4. **Logic** — concrete assertions, Tier 1-2 locators, no assertions in POMs
 
-**Optional Layer 5 — labeled DOM-probe locator cross-check (if Playwright MCP connected + app URL available):**
+**Conditional Layer 5 — labeled DOM-probe locator cross-check (runs ONLY if Playwright MCP connected + app URL available):**
 
-This layer is a STATIC locator cross-check via DOM probe. It is NOT test execution and never reports that tests passed:
+This layer is a STATIC locator cross-check via DOM probe. It is NOT test execution, MUST NEVER be substituted for a real test run, and never reports that tests passed:
 
 ```
 [DOM_PROBE — NOT_TEST_EXECUTION]
@@ -429,6 +429,7 @@ 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(
+  subagent_type="qaa-e2e-runner",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -490,6 +491,7 @@ Fix mode runs in two phases: **analyze first, then fix after user confirmation.*
 2. Invoke bug-detective agent in **classify-only mode** (no auto-fixes):
 
 Task(
+  subagent_type="qaa-bug-detective",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -536,6 +538,8 @@ Task(
   "
 )
 
+**HARD STOP on broken runner (#48):** If the bug-detective returns `runner_executed: false` / `runner_status: BROKEN` (the suite never executed — ENVIRONMENT ISSUE), do NOT present a FIX PLAN and do NOT proceed to Phase 2. Surface the ENVIRONMENT ISSUE with the runner's startup error and stop. A DOM probe is NEVER a substitute for a real run; a report claiming classifications with `runner_executed: false` is INVALID.
+
 3. Present the analysis to the user as a **fix plan**:
 
 ```
@@ -564,7 +568,7 @@ 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:
+4. **HARD STOP — Phase 1 → Phase 2 gate.** Do NOT enter Phase 2 (execute fixes) until the user EXPLICITLY approves the FIX PLAN. No approval = no fixes — this gate is mandatory and cannot be skipped, assumed, or auto-satisfied by silence. 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)
@@ -582,9 +586,12 @@ Proceed with auto-fixes? [yes / modify / cancel]
 
 #### Phase 2: Execute Fixes (only after user confirmation)
 
+**Do NOT reach this phase without an explicit "yes" / "proceed" / "dale" from the Phase 1 → Phase 2 gate above.** If you have not received explicit approval, STOP — you are still in Phase 1.
+
 5. Invoke bug-detective agent in **fix mode** with the confirmed plan:
 
 Task(
+  subagent_type="qaa-bug-detective",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-map.md

@@ -2,6 +2,40 @@
 
 Deep-scan a codebase for QA-relevant information, produce a complete analysis, and generate test inventory. Runs codebase mapping (4 parallel agents) followed by full repository analysis. One command to fully understand a codebase before writing tests.
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps. This command is flag-driven — there is no intent
+detector; read the flags from `$ARGUMENTS` literally.
+
+1. Read `CLAUDE.md` (QA standards) before anything else.
+2. Create the output directory: `mkdir -p .qa-output/codebase`.
+3. STAGE 1 — Codebase Mapping (see "## Instructions" Step 3):
+   - If neither `--skip-map` nor `--focus` was passed: spawn ALL 4
+     codebase-mapper agents IN PARALLEL (testability, risk, patterns,
+     existing-tests), each via Task() with its `<critical_directive>` block.
+   - If `--focus <area>` was passed: spawn ONLY that one agent, then STOP
+     (skip Stage 2 entirely).
+   - If `--skip-map` was passed: skip Stage 1 and go straight to Stage 2.
+4. Print the summary of documents produced by Stage 1.
+5. STAGE 2 — Repository Analysis: initialize pipeline context, then invoke the
+   scanner agent, then the analyzer agent — IN THAT ORDER, each via Task() with
+   its `<critical_directive>` block. Do NOT start the analyzer before the
+   scanner has produced SCAN_MANIFEST.md.
+6. Print the final summary of all documents produced across both stages.
+
+### DO NOT
+- Skip Stage 1 unless `--skip-map` was explicitly passed
+- Run Stage 2 when `--focus` was passed (focus mode stops after Stage 1)
+- Start the analyzer before the scanner completes
+- Run any git operation or generate any test files — this command only maps and
+  analyzes
+- Spawn the map/scan/analyze work inline instead of through the sub-agents
+- Invent steps not in this command, or reorder the ones that are
+
+If you find yourself improvising, reordering the stages, or generating tests —
+STOP and restart from step 1.
+
 ## Usage
 
 ```
@@ -79,7 +113,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 
@@ -109,7 +143,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 
@@ -139,7 +173,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 
@@ -169,7 +203,7 @@ Agent(
   trusted.
   </critical_directive>
 
-  subagent_type="general-purpose",
+  subagent_type="qaa-codebase-mapper",
   execution_context="~/.claude/qaa/agents/qaa-codebase-mapper.md"
 )
 ```
@@ -190,6 +224,7 @@ node bin/qaa-tools.cjs init qa-start 2>/dev/null || true
 Invoke scanner agent:
 
 Task(
+  subagent_type="qaa-scanner",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
@@ -230,6 +265,7 @@ Task(
 Invoke analyzer agent:
 
 Task(
+  subagent_type="qaa-analyzer",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-research.md

@@ -2,6 +2,36 @@
 
 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).
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps. This command is flag-driven — there is no intent
+detector; parse the flags from `$ARGUMENTS` literally.
+
+1. STEP 1 — Initialize (see "## Instructions"): parse `$ARGUMENTS` for `--focus`
+   and `--dev-repo`, resolve MODE (default `stack-testing`) and DEV_REPO
+   (default: current directory), create `.qa-output/research/`, and print the
+   `=== QA Research ===` banner.
+2. STEP 2 — Read existing context if present: `.qa-output/SCAN_MANIFEST.md`,
+   `CLAUDE.md`, `~/.claude/qaa/MY_PREFERENCES.md`.
+3. STEP 3 — Spawn the project-researcher via Task() with its `<critical_directive>`
+   block, passing the resolved MODE and DEV_REPO. Do NOT do the research inline.
+4. STEP 4 — After the researcher returns, print the `=== Research Complete ===`
+   summary.
+5. Run the "## MANDATORY verification" checklist at the bottom of this file
+   before returning control.
+
+### DO NOT
+- Skip the `=== QA Research ===` banner
+- Do the research yourself inline instead of spawning the project-researcher
+- Invent a mode not in the `--focus` list, or reorder the steps
+- Skip the bottom verification checklist
+- Assume dev-repo path or mode from a previous command invocation — each
+  /qa-research call is self-contained
+
+If you find yourself improvising, doing the research inline, or skipping the
+verification checklist — STOP and restart from step 1.
+
 ## Usage
 
 ```
@@ -95,6 +125,7 @@ Read these files if they exist — they provide context to the researcher:
 ### Step 3: Spawn Researcher Agent
 
 Task(
+  subagent_type="qaa-project-researcher",
   prompt="
     <critical_directive priority="MANDATORY">
     You are executing as a QAA pipeline agent. Your FIRST action MUST be to read

package/commands/qa-test-report.md

@@ -2,6 +2,41 @@
 
 Generate a per-ticket QA execution summary and append it to the Azure DevOps work item's `Custom.QATestCasesReport` field. For each test case linked to the work item, pull the execution status from ADO Test Runs — or prompt the user when ADO has no run result — then render a bulleted "Tested Scenarios" list (with a separate "Failures" section when anything failed).
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps. This command reads Azure DevOps and writes ONLY
+the `Custom.QATestCasesReport` field; it spawns no sub-agents and creates no
+test cases.
+
+1. PHASE 1 — Resolve the work item: if `$ARGUMENTS` has no work item ID, ask the
+   user before proceeding. Fetch it with `wit_get_work_item` (relations) plus
+   its comments.
+2. PHASE 2 — Resolve the test-case list. ADO is authoritative: build the list
+   from the *Tested By* links; a local `test-cases.md` is only a hint. If no TCs
+   are linked, print "nothing to report" and STOP.
+3. PHASE 3 — Resolve each TC's status (Passed/Failed/Blocked): try the ADO Test
+   Points REST endpoint first; for any TC that doesn't resolve, ask the user. For
+   Failed TCs, capture a reason (run data → comments → ask the user).
+4. PHASE 4 — Synthesize a readable one-line scenario description per TC (not the
+   raw TC title).
+5. PHASE 5 — Build BOTH the markdown (for chat) and HTML (for the field) reports.
+   Include the Failures section only if something failed.
+6. PHASE 6 — APPEND the HTML report to `Custom.QATestCasesReport`: re-read the
+   current value and preserve it (existing + `<br><br>` + new). Update ONLY that
+   field — never overwrite others.
+7. PHASE 7 — Print the markdown report + the append confirmation to the user.
+
+### DO NOT
+- OVERWRITE `Custom.QATestCasesReport` — always append, preserving prior content
+- Write to any field other than `Custom.QATestCasesReport`
+- Create test cases, change TC state, or create Test Runs (this command is read-mostly)
+- Copy raw TC titles as scenario descriptions when they are terse
+- Invent steps not in this command, or reorder the phases
+
+If you find yourself overwriting the field, touching other fields, or creating or
+modifying test cases — STOP and restart from step 1.
+
 ## Usage
 
 ```

package/commands/qa-testid.md

@@ -2,6 +2,37 @@
 
 Scan frontend source code, audit missing data-testid attributes, and inject them following the naming convention in CLAUDE.md. Creates a separate branch for the changes.
 
+## ⚠ MANDATORY: How to Execute This Command
+
+Execute these steps IN ORDER. Every step is mandatory. Do NOT improvise,
+reorder, skip, or invent steps.
+
+1. Read `CLAUDE.md` — the data-testid Convention section — before anything else.
+2. Execute `workflows/qa-testid.md` end-to-end, in order, without skipping steps.
+3. Preserve ALL workflow gates. In particular, do NOT bypass:
+   - **Framework detection** (workflow Step 2, `detect_frontend`): if no frontend
+     directory, no framework, or no component files are found, STOP with the
+     workflow's error — do NOT proceed to injection.
+   - **Audit checkpoint / user approval** (workflow Step 4, CHECKPOINT phase):
+     the testid-injector MUST present TESTID_AUDIT_REPORT.md and wait for the
+     user to approve proposed values BEFORE injecting. Do NOT inject without it.
+   - **Branch creation** (workflow Step 4 INJECT phase / Step 5,
+     `create_branch_and_commit`): injection happens ONLY on the separate branch
+     `qa/testid-inject-{YYYY-MM-DD}` — never on the working branch.
+4. Spawn the scanner and testid-injector via Task() with their
+   `<critical_directive>` blocks, as the workflow specifies — do NOT do the
+   scan/audit/injection inline.
+
+### DO NOT
+- Inject any data-testid before the user approves the audit report
+- Modify source files on the working branch (injection is branch-isolated)
+- Change application logic — only add data-testid attributes
+- Skip framework detection or proceed when it reports no frontend
+- Invent steps not in the workflow, or reorder them
+
+If you find yourself injecting before approval, working off-branch, or skipping
+the framework-detection gate — STOP and restart from step 1.
+
 ## Usage
 
 /qa-testid [<source-directory>]

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "qaa-agent",
-  "version": "1.9.5",
-  "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"
-  },
-  "keywords": [
-    "qa",
-    "automation",
-    "testing",
-    "claude-code",
-    "playwright",
-    "jest",
-    "pytest",
-    "ai-agent"
-  ],
-  "author": "Backhaus7997",
-  "license": "MIT",
-  "dependencies": {
-    "@playwright/mcp": "latest",
-    "@upstash/context7-mcp": "latest"
-  },
-  "files": [
-    "bin/",
-    "agents/",
-    "workflows/",
-    "templates/",
-    "docs/COMMANDS.md",
-    "docs/DEMO.md",
-    "docs/TESTING.md",
-    "commands/",
-    "skills/",
-    "frameworks/",
-    "settings.json",
-    ".mcp.json",
-    "CLAUDE.md",
-    "CHANGELOG.md",
-    "VERSION"
-  ]
-}
+{
+  "name": "qaa-agent",
+  "version": "1.9.6",
+  "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"
+  },
+  "keywords": [
+    "qa",
+    "automation",
+    "testing",
+    "claude-code",
+    "playwright",
+    "jest",
+    "pytest",
+    "ai-agent"
+  ],
+  "author": "Backhaus7997",
+  "license": "MIT",
+  "dependencies": {
+    "@playwright/mcp": "latest",
+    "@upstash/context7-mcp": "latest"
+  },
+  "files": [
+    "bin/",
+    "agents/",
+    "workflows/",
+    "templates/",
+    "docs/COMMANDS.md",
+    "docs/DEMO.md",
+    "docs/TESTING.md",
+    "commands/",
+    "skills/",
+    "frameworks/",
+    "settings.json",
+    ".mcp.json",
+    "CLAUDE.md",
+    "CHANGELOG.md",
+    "VERSION"
+  ]
+}