qaa-agent 1.9.5 → 1.9.7

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 
 All notable changes to QAA (QA Automation Agent) are documented here.
 
+## [1.9.7] - 2026-07-29
+
+### Added
+
+- **Pre-flight checks with UX-friendly error messages across all 10 commands** — every slash command now runs guard checks before its main flow and, on failure, prints a clear, actionable error: a one-line title, a short explanation, two or three concrete options, and a `Try:` command. Coverage includes invalid `--dev-repo`/source paths, missing required MCP servers (Playwright for `/qa-audit`, `/qa-testid`, `/qa-create-test` from-aut and `/qa-fix --run`; Context7 for `/qa-research`; Azure DevOps for `/qa-create-test-ado` and `/qa-test-report`), undetectable frameworks, non-git repositories, and a missing/unauthenticated GitHub CLI. Required-dependency failures STOP; optional-enhancement failures (e.g. live DOM verification) WARN and continue in degraded mode. Every suggested flag is validated against what the command actually accepts.
+
+### Fixed
+
+- **Installer now syncs `workflows/` to the live location** — `install.cjs` Step 4 mirrors `workflows/qa-*.md` into `<claudeDir>/workflows/` alongside commands and agents, using the same scope-aware sync. Commands reference workflows via `@workflows/qa-*.md`; syncing them makes that resolution direct instead of a fallback runtime search, on every install (global or local).
+
+### Documentation
+
+- **QAA_SYSTEM_OVERVIEW.md refreshed for the current system state** — the Installation section now documents the four installer steps, including the live sync of commands, agents, workflows, and CLAUDE.md to the locations Claude Code loads from.
+
+## [1.9.6] - 2026-07-14
+
+### Added
+
+- **Native subagent routing across the 5 active commands** — all 12 QAA agents are now registered as native Claude Code subagents (added YAML frontmatter to `qaa-scanner` and `qaa-discovery`, the last two that lacked it). `/qa-fix`, `/qa-audit`, `/qa-map`, `/qa-research`, and `/qa-create-test` now spawn their sub-agents via `subagent_type="qaa-X"` for direct routing. The change is additive: the embedded Task() directive is kept in every spawn as a fallback for environments where native routing isn't available yet (e.g. a fresh install before restart).
+- **Context7 cache cascade wired into the executor's generation process** — the executor now runs the cache cascade (cache → research docs → query Context7 → write back) as an explicit step before generating files, instead of only declaring it in a side section. Reduces redundant Context7 calls during generation.
+- **`--dev-repo` natural-language alias in `/qa-audit`** — the intent detector now resolves a dev-repo path from natural language for the audit command (for coverage cross-reference), not only from the explicit flag.
+- **Non-numeric project-key ticket detection** — the intent detector now recognizes standalone ticket references like `#PROJ-abc-fix` (uppercase project prefix + hyphen), in addition to numeric refs, without matching plain words.
+
+### Changed
+
+- **MANDATORY execution headers extended to the remaining natural-language commands** — `/qa-audit`, `/qa-map`, `/qa-research`, and `/qa-testid` now open with a `## ⚠ MANDATORY: How to Execute This Command` block defining their full ordered flow plus DO / DO NOT, matching the commands that already had it. (`/qa-audit`'s partial "First Tool Call" header was upgraded to the full form.)
+- **MANDATORY verification headers added to the remaining agents** — `qaa-scanner`, `qaa-codebase-mapper`, `qaa-discovery`, and `qaa-project-researcher` now carry the `## MANDATORY verification` header before their bash checklist, matching the other agents.
+- **`CLAUDE.md` updated to reflect native routing is enabled** — the "Standard Task() Directive" section no longer claims native `subagent_type` routing is disabled; it documents native routing as the primary mechanism where wired, with the directive as the fallback.
+
+### Fixed
+
+- **`/qa-fix` FIX MODE no longer allows a silent Phase 1 → Phase 2 transition** — the confirmation checkpoint before applying fixes is now an explicit HARD STOP gate (no approval = no fixes), and Phase 2 restates that it must not be reached without explicit user approval.
+- **DOM-probe wording tightened to prevent substitution for real test runs** — the `/qa-fix` locator cross-check layer is relabeled from "Optional" to "Conditional" (it still runs only when Playwright MCP and an app URL are available) and now states the probe MUST NEVER be substituted for a real test run. A command-level runner HARD STOP was added: if the test runner cannot execute, the command reports an ENVIRONMENT ISSUE and stops instead of falling back to a DOM probe.
+
+### Documentation
+
+- **Context7 `resolve-library-id` call shape documented** — `qaa-project-researcher`, `qaa-executor`, `qaa-e2e-runner`, and `qaa-bug-detective` now note that the library name is passed as a string via `libraryName` (`{ libraryName: "<string>" }`) and what an "expected: string" validation error indicates.
+
 ## [1.9.5] - 2026-05-05
 
 ### Added

package/CLAUDE.md

@@ -679,7 +679,9 @@ These are **Capa 1** of a 3-layer validation system. Capa 2 is each agent's `<qu
 
 ## Standard Task() Directive
 
-Every `Task()` / `Agent()` spawn in this codebase (orchestrator, commands, workflows) MUST embed the following directive **verbatim** at the very top of the spawned prompt, substituting ONLY `<AGENT_FILE>` with the target agent's exact filename (e.g. `qaa-scanner`, `qa-pipeline-orchestrator`). Do NOT paraphrase it, and do NOT add `subagent_type: "qaa-X"` — native subagent routing for QAA agents is not enabled and would hard-error (see the architectural note below).
+Every `Task()` / `Agent()` spawn in this codebase (orchestrator, commands, workflows) MUST embed the following directive **verbatim** at the very top of the spawned prompt, substituting ONLY `<AGENT_FILE>` with the target agent's exact filename (e.g. `qaa-scanner`, `qa-pipeline-orchestrator`). Do NOT paraphrase it.
+
+Native subagent routing **is enabled** for the 12 QAA agents — they are registered in `~/.claude/agents/` with YAML frontmatter (verified via live routing smoke tests). Spawns SHOULD therefore set `subagent_type: "qaa-X"` to route directly to the dedicated agent. The directive below is retained in every spawn prompt as a **fallback**: it preserves the operating contract even where native routing isn't available yet (e.g. a fresh install before Claude Code is restarted). As of v1.9.6 the 5 active commands (qa-fix, qa-audit, qa-map, qa-research, qa-create-test) use native `subagent_type`; `workflows/qa-start.md` and the orchestrator still rely on the directive alone (see architectural note below).
 
 ```
 <critical_directive priority="MANDATORY">
@@ -712,7 +714,7 @@ trusted.
 QAA hardens execution at two layers, and new commands/agents MUST follow both:
 
 1. **Command headers** — every NL command opens with a `## ⚠ MANDATORY: How to Execute This Command` block defining the full ordered flow + DO / DO NOT (not just the first tool call).
-2. **Task() prompts** — every spawn embeds the Standard Task() Directive above.
+2. **Task() prompts** — every spawn sets `subagent_type: "qaa-X"` for native routing (where wired) AND embeds the Standard Task() Directive above as a fallback.
 
-This is the standard QAA enforcement pattern. Native `subagent_type` routing is deferred (the agents are not registered in `~/.claude/agents/`); until then the embedded directive is the enforcement mechanism.
+This is the standard QAA enforcement pattern. Native `subagent_type` routing **is now enabled** (all 12 agents are registered in `~/.claude/agents/`), so it is the primary routing mechanism where wired; the embedded directive remains as the **fallback** that guarantees the operating contract even when native routing is unavailable. Removing the directive is deferred to a future cleanup once native routing has been proven in production.
 

package/VERSION

@@ -1 +1 @@
-1.9.5
+1.9.7

package/agents/qaa-bug-detective.md

@@ -93,6 +93,8 @@ When the project's framework version is known (detected from `package.json`, `re
 ```
 # 1. Resolve base libraryId
 RESOLVED_ID = mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+# SHAPE: pass the name as a STRING via `libraryName` → { libraryName: "<string>" }.
+# An "expected: string" validation error means the argument shape is wrong (don't pass a bare string).
 # example: "/microsoft/playwright"
 
 # 2. If project version is detected (e.g., "1.40.0"):

package/agents/qaa-codebase-mapper.md

@@ -945,6 +945,10 @@ Before considering codebase mapping complete, verify ALL of the following:
 If any check fails, fix the issue before returning. Do not deliver codebase docs that fail their own quality gate.
 </quality_gate>
 
+## 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_checklist>
 Run this checklist verbatim before returning control:
 

package/agents/qaa-discovery.md

@@ -1,3 +1,9 @@
+---
+name: qaa-discovery
+description: Interactive QA discovery agent — gathers project context, risk priorities, and scope at three checkpoints (pre-scan, mid-pipeline, post-validate).
+tools: Read, Write, Bash, Grep, Glob, AskUserQuestion
+---
+
 <purpose>
 Extract the context and decisions needed to run a high-quality QA pipeline. This agent runs at three points:
 
@@ -378,6 +384,10 @@ Before considering the discovery checkpoint complete, verify ALL of the followin
 If --auto and no input expected, return immediately with skipped status. Otherwise wait for user input.
 </quality_gate>
 
+## 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_checklist>
 Run this checklist verbatim before returning:
 

package/agents/qaa-e2e-runner.md

@@ -91,6 +91,8 @@ When the project's framework version is known (detected from `package.json`, `re
 ```
 # 1. Resolve base libraryId
 RESOLVED_ID = mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+# SHAPE: pass the name as a STRING via `libraryName` → { libraryName: "<string>" }.
+# An "expected: string" validation error means the argument shape is wrong (don't pass a bare string).
 # example: "/microsoft/playwright"
 
 # 2. If project version is detected (e.g., "1.40.0"):

package/agents/qaa-executor.md

@@ -157,6 +157,8 @@ When the project's framework version is known (detected from `package.json`, `re
 ```
 # 1. Resolve base libraryId
 RESOLVED_ID = mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+# SHAPE: pass the name as a STRING via `libraryName` → { libraryName: "<string>" }.
+# An "expected: string" validation error means the argument shape is wrong (don't pass a bare string).
 # example: "/microsoft/playwright"
 
 # 2. If project version is detected (e.g., "1.40.0"):
@@ -404,6 +406,23 @@ Only commit if files were actually created. If all infrastructure already exists
 <step name="generate_per_task">
 For each task in the generation plan (in dependency order from topological sort), generate the assigned files.
 
+**Before generating — resolve framework docs via the Context7 cache cascade (run this here so it is actually exercised, not just declared in the section above):**
+
+For the detected `{framework}` + `{version}` (from SCAN_MANIFEST.md / the framework registry), resolve the selector/locator + assertion API BEFORE writing any file:
+
+1. **Read cache first:**
+   ```bash
+   CACHED=$(node ~/.claude/qaa/bin/lib/context7-cache.cjs read {framework} {version} "generation-api" 2>/dev/null)
+   ```
+2. If `CACHED` is a hit → use it; skip the Context7 call.
+3. If cache miss → check research docs (`.qa-output/research/FRAMEWORK_CAPABILITIES.md`, `.qa-output/research/TESTING_STACK.md`). If they cover the API → use them.
+4. If both miss → query Context7 (`resolve-library-id` → `query-docs`), then write the response back to cache for next time:
+   ```bash
+   node ~/.claude/qaa/bin/lib/context7-cache.cjs write {framework} {version} "generation-api" "$RESPONSE"
+   ```
+
+Do NOT generate framework-specific syntax from memory when the cascade can supply the verified API. See `<context7_verification>` for the full cascade contract.
+
 **Execution loop:**
 
 For each task (ordered by dependencies):

package/agents/qaa-project-researcher.md

@@ -170,6 +170,8 @@ When the project's framework version is known (detected from `package.json`, `re
 ```
 # 1. Resolve base libraryId
 RESOLVED_ID = mcp__context7__resolve-library-id({ libraryName: "{framework-name}" })
+# SHAPE: pass the name as a STRING via `libraryName` → { libraryName: "<string>" }.
+# An "expected: string" validation error means the argument shape is wrong (don't pass a bare string).
 # example: "/microsoft/playwright"
 
 # 2. If project version is detected (e.g., "1.40.0"):
@@ -480,6 +482,10 @@ Before considering research complete, verify ALL of the following:
 If any check fails, fix before delivering. The researcher must NOT commit; the orchestrator commits.
 </quality_gate>
 
+## 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_checklist>
 Run this checklist verbatim before returning:
 

package/agents/qaa-scanner.md

@@ -1,3 +1,9 @@
+---
+name: qaa-scanner
+description: Scans a developer repo to produce SCAN_MANIFEST.md — detects framework, language, runtime, and testable surfaces. First stage of the QA pipeline.
+tools: Read, Write, Bash, Grep, Glob
+---
+
 <purpose>
 Scan a developer repository to produce a comprehensive SCAN_MANIFEST.md. Reads the repo's file tree, package manifests, configuration files, and source code to detect framework, language, runtime, and all testable surfaces. This agent is spawned by the orchestrator as the first stage of the QA automation pipeline. It accepts a DEV repo path and an output path from the orchestrator prompt, scans the target repository, and writes a structured manifest that downstream agents (qa-analyzer, qa-testid-injector) consume without needing to re-read the source repository.
 </purpose>
@@ -456,6 +462,9 @@ Before considering the scan complete, verify ALL of the following.
 If any check fails, fix the issue before writing the final output. Do not proceed with a failing quality gate.
 </quality_gate>
 
+## 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_checklist>
 Run this checklist verbatim before returning:

package/bin/install.cjs

@@ -320,8 +320,10 @@ async function main() {
   //
   // Claude Code loads slash commands from <claudeDir>/commands, sub-agents from
   // <claudeDir>/agents, and global standards from <claudeDir>/CLAUDE.md — NOT
-  // from the qaa/ install dir. Mirror QAA files there so new versions activate.
-  // Only QAA-owned files (qa*.md / qaa-*.md) are touched.
+  // from the qaa/ install dir. Commands also reference workflows via
+  // @workflows/qa-*.md; mirroring workflows to <claudeDir>/workflows makes that
+  // resolution direct instead of a fragile runtime search. Mirror QAA files
+  // there so new versions activate. Only QAA-owned files (qa*.md) are touched.
 
   console.log('');
 
@@ -344,6 +346,14 @@ async function main() {
   success(`${tag}Live agents → ${path.join(claudeDir, 'agents')} (${agentSync.copied.length} synced${agentSync.pruned.length ? `, ${agentSync.pruned.length} pruned` : ''})`);
   if (agentSync.pruned.length) log(`${tag}Pruned: ${agentSync.pruned.join(', ')}`);
 
+  const workflowSync = syncLive(
+    path.join(installDir, 'workflows'),
+    path.join(claudeDir, 'workflows'),
+    qaMatch, dryRun
+  );
+  success(`${tag}Live workflows → ${path.join(claudeDir, 'workflows')} (${workflowSync.copied.length} synced${workflowSync.pruned.length ? `, ${workflowSync.pruned.length} pruned` : ''})`);
+  if (workflowSync.pruned.length) log(`${tag}Pruned: ${workflowSync.pruned.join(', ')}`);
+
   const cmd = syncClaudeMd(installDir, claudeDir, dryRun, pkgVersion);
   if (cmd.action === 'created')              success(`${tag}CLAUDE.md created (QAA markers) → ${path.join(claudeDir, 'CLAUDE.md')}`);
   else if (cmd.action === 'updated-section') success(`${tag}CLAUDE.md QAA section updated → ${path.join(claudeDir, 'CLAUDE.md')}`);
@@ -359,7 +369,7 @@ async function main() {
   console.log('');
   if (dryRun) log('Dry-run complete — nothing was written.');
   log(`${totalFiles} files installed to ${installDir}`);
-  log(`Live commands & agents synced to ${claudeDir}`);
+  log(`Live commands, agents & workflows synced to ${claudeDir}`);
   log('MCP servers: playwright, context7');
   log('');
   log('Restart Claude Code, then run any QAA command:');

package/bin/lib/intent-detector.cjs

@@ -175,15 +175,17 @@ function detectFramework(text) {
 }
 
 // Ticket references in FREE TEXT (not URLs): "ticket #PROJ-123", "issue 42",
-// "#v195-fixes". Keyword-anchored matches are most reliable; a standalone
-// "#id" is accepted only when it contains a digit (avoids matching plain words
-// like "#fixes"). Returns the bare id (leading "#" stripped) for branch naming.
+// "#v195-fixes", "#PROJ-abc-fix". Keyword-anchored matches are most reliable; a
+// standalone "#id" is accepted when it contains a digit OR looks like a
+// project key (UPPERCASE prefix + hyphen, e.g. PROJ-abc-fix) — this avoids
+// matching plain words like "#fixes". Returns the bare id (leading "#"
+// stripped) for branch naming.
 function detectTicketRefs(text) {
   const refs = [];
   const kw = text.match(/\b(?:ticket|issue|story|bug)\s+#?([A-Za-z0-9][\w.\-]*)/i);
   if (kw) refs.push(kw[1]);
   for (const m of text.matchAll(/(?:^|\s)#([A-Za-z0-9][\w.\-]*)/g)) {
-    if (/\d/.test(m[1]) && !refs.includes(m[1])) refs.push(m[1]);
+    if ((/\d/.test(m[1]) || /^[A-Z][A-Za-z0-9]*-/.test(m[1])) && !refs.includes(m[1])) refs.push(m[1]);
   }
   return refs;
 }

package/commands/qa-audit.md

@@ -3,43 +3,54 @@
 Comprehensive quality audit of a test suite with 6-dimension scoring, testing pyramid analysis, and status reporting. Supports three output modes: full audit, pyramid analysis only, or status report adapted to audience.
 
 
-## ⚠ MANDATORY: First Tool Call
-
-Before any other tool use, you **MUST** run the intent detector as your **FIRST** tool call. Do NOT explore the repo, do NOT analyze the prompt independently, do NOT make assumptions about what the user wants. Run this first:
-
-```bash
-RESOLVED=$(node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" --aliases '{"app_url":"app-url"}')
-echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.banner)"
-```
-
-**Pass `$ARGUMENTS` LITERALLY** — do NOT mentally translate NL to flag form. The detector handles NL parsing. If you pre-translate, the detector reports `source: flag` for everything and bypasses the confirmation checkpoint.
-
-### After the banner appears
-
-1. Determine `ALL_FROM_FLAGS`:
+## ⚠ 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). Do
+   NOT show a custom-format banner.
+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')")
    ```
-
-2. If **`IS_AUTO=false` AND `ALL_FROM_FLAGS=false`** (some values came from NL or defaults), **PAUSE and ask the user**:
+   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)
    ```
-   Wait for explicit user confirmation before proceeding.
-
-3. If `IS_AUTO=true` OR `ALL_FROM_FLAGS=true`, proceed without pause.
+4. Determine MODE from the resolved values (not from your own NL parsing):
+   `--pyramid` → PYRAMID MODE, `--report` → REPORT MODE, otherwise AUDIT MODE.
+5. Read `CLAUDE.md` and `~/.claude/qaa/MY_PREFERENCES.md` (if it exists) before
+   invoking any agent.
+6. Execute the mode's flow IN ORDER (see "## Instructions"). Every mode invokes
+   its sub-agent via Task() with the `<critical_directive>` block — AUDIT MODE
+   spawns the validator; PYRAMID and REPORT MODE spawn the analyzer. Do NOT run
+   the audit/analysis inline; always go through the sub-agent. Present results
+   only after the agent returns.
 
 ### DO NOT
+- Skip the INPUT DETECTION banner, or show a custom-format banner
+- Run AskUserQuestion, Bash, Read, or Glob before the intent detector
+- Decide the mode before the detector runs, or from your own NL parsing
+- Run the audit/pyramid/report analysis inline instead of spawning the sub-agent
+- Invent steps not in this command, or reorder the ones that are
+- Assume path, app URL, or any value from a previous command invocation — each
+  /qa-audit call is self-contained
 
-- Show a custom-format banner — use the exact output from `intent-detector.cjs`
-- Skip the detector and parse NL in your own head
-- Decide mode (from-aut, from-ticket, etc.) before the detector runs
-- Make tool calls (Bash, Read, Glob) before the detector runs
+If you find yourself improvising, presenting results before the agent returns,
+or asking questions out of order — STOP and restart from step 1.
 
-### Mode detection happens AFTER the detector
+### Pass user input literally to the intent detector
 
-Use the resolved values from `RESOLVED` (URLs, framework, paths) to determine mode. The detector's `intent.suggested_mode` already provides a heuristic.
+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
@@ -81,7 +92,7 @@ else:
 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"}')
+RESOLVED=$(node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" --aliases '{"app_url":"app-url","dev_repo":"dev-repo"}')
 
 # 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)"
@@ -92,6 +103,43 @@ APP_URL=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileS
 
 If you see values you didn't intend in the banner above (interactive mode), you can press Ctrl-C and re-run with explicit flags.
 
+## Pre-flight checks
+
+Run these BEFORE the main flow. A **[STOP]** check that fails: print the error EXACTLY as shown (fill in the `{...}` placeholders) and STOP. A **[WARN]** check that fails: print the notice and continue in degraded mode.
+
+### Dev-repo path does not exist — --dev-repo given [STOP]
+If `--dev-repo` was passed (coverage cross-reference) but the path does not exist:
+```
+❌ Dev-repo path not found: {path}
+
+You passed --dev-repo for coverage cross-reference, but that path does not exist
+(or is not a directory).
+
+Options:
+  1. Re-run with a correct path: /qa-audit <tests> --dev-repo <path>
+  2. Drop --dev-repo to audit the test suite without coverage cross-reference
+  3. Check for a typo or an unexpanded ~ in the path
+
+Try: ls {path}
+```
+
+### Playwright MCP not connected — --app-url given [WARN]
+If `--app-url` was passed (live locator verification) but Playwright MCP is unavailable:
+```
+❌ Playwright MCP is not connected — live locator verification will be skipped.
+
+You passed --app-url so /qa-audit can check test locators against the real DOM
+via Playwright MCP. It isn't available, so that check can't run — the rest of
+the audit still proceeds.
+
+Options:
+  1. Connect Playwright MCP (ships with QAA — check ~/.claude.json), then re-run for full verification
+  2. Reinstall to re-register the MCP servers: npx qaa-agent
+  3. Continue now with static scoring only (no live DOM verification)
+
+Try: /mcp
+```
+
 ## Instructions
 
 ### AUDIT MODE (default)
@@ -103,6 +151,7 @@ Scores across 6 dimensions: Locator Quality (20%), Assertion Specificity (20%),
 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
@@ -156,6 +205,7 @@ Analyze test distribution against the ideal testing pyramid from CLAUDE.md (Unit
 2. Invoke analyzer agent for pyramid analysis:
 
 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
@@ -212,6 +262,7 @@ Generate a summary report of current QA status. Adapts detail level to audience.
 2. Invoke analyzer agent for status reporting:
 
 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