qaa-agent 1.9.1 → 1.9.5

package/workflows/qa-start.md

@@ -1,6 +1,70 @@
+<critical_directive priority="MANDATORY">
+
+## ⚠ MANDATORY EXECUTION RULES — READ AND OBEY BEFORE ANYTHING ELSE
+
+These rules are non-negotiable. Read them before any other section of this file.
+
+### Rule 1 — Execute every step literally
+
+This workflow is a script, NOT a guide. Run each `<step>` in order. Do NOT skip steps. Do NOT reorder steps. Do NOT adapt steps to "fit" the user's situation.
+
+### Rule 2 — Your FIRST tool call MUST be the bash block in Step 1 (initialize)
+
+Specifically: run `node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve ...` as your very first action. Do NOT explore the repo first. Do NOT analyze the user's prompt independently. Do NOT make assumptions about whether the pipeline "applies".
+
+### Rule 3 — NEVER improvise an alternative pipeline
+
+If you find yourself thinking "the standard pipeline doesn't apply because [empty repo / external URL / different framework / X / Y]", **STOP**. The pipeline applies. Run it as written.
+
+If a stage genuinely cannot complete, the workflow itself handles that case (with non-blocking failures, fallbacks, or stop-pipeline directives). Your job is to **execute**, not to redesign.
+
+### Rule 4 — If a step fails, report failure — do not adapt
+
+When a bash command fails or a sub-agent returns an error, report it as a pipeline failure following the `<error_handling>` rules at the bottom of this file. Do NOT "work around" it. Do NOT scaffold an alternative.
+
+### Rule 5 — Empty target repos are NORMAL and expected
+
+The pipeline handles empty repos. Many stages produce skeleton output or report "nothing to do" for empty repos. This is **by design**. Do NOT interpret "empty repo" as a signal to abandon the workflow and start scaffolding things directly.
+
+### Rule 6 — Your role is execution, not architecture
+
+You are running a defined process. The user chose this process by invoking `/qa-start`. Do NOT second-guess the design. Do NOT decide that a different approach would be better. Run the workflow.
+
+### Rule 7 — Pass `$ARGUMENTS` to the intent detector LITERALLY
+
+When Step 1 says `node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" ...`, the placeholder `$ARGUMENTS` must be substituted with the **raw user input as received**, with no mental translation, parsing, or restructuring.
+
+**WRONG** — pre-translating NL to flag form before invoking the detector:
+```
+# User prompt: "from URL https://x.com to C:\foo using cypress"
+# DON'T DO THIS:
+node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve '--app-url https://x.com --dev-repo "C:\foo" --framework cypress' ...
+```
+
+**RIGHT** — passing the raw prompt as-is so the detector does its job:
+```
+node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve 'from URL https://x.com to C:\foo using cypress' ...
+```
+
+The detector handles NL parsing. If you pre-translate, the detector sees flags and reports `source: flag` for everything, which **bypasses the confirmation checkpoint** that exists specifically to catch NL-misinterpretation errors. That defeats the purpose.
+
+### Failure mode to recognize and prevent: IMPROVISATION
+
+If, after reading this workflow, you find yourself doing any of the following, you have FAILED:
+
+- Listing the target repo and saying "this is empty, I'll scaffold files directly"
+- Saying "the standard pipeline assumes X, I'll adapt"
+- Calling sub-agents that the workflow does not explicitly invoke
+- Generating files (.spec.ts, .robot, etc.) before reaching the `<step name="generate">` stage
+- Skipping the `<step name="initialize">` bash block and going straight to other steps
+
+If you catch yourself about to do any of these, **stop, return to the top of this workflow, and execute Step 1 first**.
+
+</critical_directive>
+
 <purpose>
 
-Orchestrate the full QA automation pipeline: scan -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [bug-detective if failures] -> deliver. Detects workflow option (1/2/3) from arguments, spawns specialized agents for each stage, manages state transitions, handles checkpoints (safe auto-approve, risky always pause), and delivers a draft PR with per-stage atomic commits.
+Orchestrate the full QA automation pipeline: scan -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective if failures] -> deliver. Detects workflow option (1/2/3) from arguments, spawns specialized agents for each stage, manages state transitions, handles checkpoints (safe auto-approve, risky always pause), and delivers a draft PR with per-stage atomic commits.
 
 Invoked by the `/qa-start` slash command. Accepts `--dev-repo`, `--qa-repo`, and `--auto` flags.
 
@@ -21,36 +85,134 @@ Read these files BEFORE executing any pipeline stage. Do NOT skip.
 
 ## Step 1: Initialize Pipeline
 
-Parse `$ARGUMENTS` for flags:
+Parse `$ARGUMENTS` using the intent detector (handles flags + natural language + paths with spaces):
 
 ```bash
-DEV_REPO=""
-QA_REPO=""
-IS_AUTO=false
+# Resolve flags + NL + defaults via shared intent detector
+# IMPORTANT: $ARGUMENTS must be the RAW user input, NOT a pre-translated flag string.
+# The detector handles NL parsing — pre-translation defeats the confirmation checkpoint.
+RESOLVED=$(node ~/.claude/qaa/bin/lib/intent-detector.cjs --resolve "$ARGUMENTS" --aliases '{"dev_repo":"dev-repo","qa_repo":"qa-repo","app_url":"app-url","framework":"framework"}')
+
+# Extract resolved values
+DEV_REPO=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.dev_repo?.value || '')")
+QA_REPO=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.qa_repo?.value || '')")
+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 || '')")
+IS_AUTO=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.resolved.auto?.value === true ? 'true' : 'false')")
+
+# Print the INPUT DETECTION banner (always shown — with flags, with NL, or defaults)
+echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.banner)"
+```
 
-# Parse --dev-repo flag
-if echo "$ARGUMENTS" | grep -qE '\-\-dev-repo'; then
-  DEV_REPO=$(echo "$ARGUMENTS" | grep -oE '\-\-dev-repo\s+[^\s]+' | awk '{print $2}')
+**If no --dev-repo provided and not detected from NL**, use the current working directory:
+```bash
+if [ -z "$DEV_REPO" ]; then
+  DEV_REPO=$(pwd)
+  echo "  (no dev-repo specified, defaulting to cwd: $DEV_REPO)"
 fi
+```
+
+**Input Validation (5 pre-pipeline checks — Capa 1 of 3-layer validation system):**
 
-# Parse --qa-repo flag
-if echo "$ARGUMENTS" | grep -qE '\-\-qa-repo'; then
-  QA_REPO=$(echo "$ARGUMENTS" | grep -oE '\-\-qa-repo\s+[^\s]+' | awk '{print $2}')
+```bash
+echo "=== INPUT VALIDATION ==="
+VALIDATION_FAIL=false
+
+# Check 1: URL reachable (warning only, not fatal)
+if [ -n "$APP_URL" ]; then
+  if curl -sf -o /dev/null -m 5 "$APP_URL" 2>/dev/null; then
+    echo "  OK: AUT URL reachable ($APP_URL)"
+  else
+    echo "  WARN: AUT URL not reachable from this network — proceeding anyway"
+  fi
 fi
 
-# Parse --auto flag
-if echo "$ARGUMENTS" | grep -qE '\-\-auto'; then
-  IS_AUTO=true
+# Check 2: Path destino writable or creatable
+if [ -n "$DEV_REPO" ]; then
+  if [ -d "$DEV_REPO" ] && [ -w "$DEV_REPO" ]; then
+    echo "  OK: dev-repo path exists and is writable"
+  elif [ ! -d "$DEV_REPO" ]; then
+    parent=$(dirname "$DEV_REPO")
+    if [ -d "$parent" ] && [ -w "$parent" ]; then
+      echo "  OK: dev-repo path can be created"
+    else
+      echo "  FAIL: dev-repo path is not writable: $DEV_REPO"
+      VALIDATION_FAIL=true
+    fi
+  fi
+fi
+
+# Check 3: URL not ambiguous with ticket platforms
+if [ -n "$APP_URL" ]; then
+  if echo "$APP_URL" | grep -qE "github\.com.*(issues|pull)|atlassian\.net|linear\.app|dev\.azure\.com"; then
+    echo "  WARN: $APP_URL looks like a ticket URL — did you mean /qa-from-ticket? Proceeding anyway."
+  fi
+fi
+
+# Check 4: No multiple AUT URLs detected
+URL_COUNT=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.intent.aut_urls.length)")
+if [ "$URL_COUNT" -gt 1 ]; then
+  echo "  FAIL: $URL_COUNT AUT URLs detected, expected at most 1"
+  echo "  Found: $(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(j.intent.aut_urls.join(', '))")"
+  VALIDATION_FAIL=true
+fi
+
+# Check 5: Framework target exists in registry (warn if not, falls back to Context7)
+if [ -n "$FRAMEWORK" ]; then
+  if [ -f "frameworks/${FRAMEWORK}.json" ]; then
+    echo "  OK: framework '$FRAMEWORK' found in registry"
+  else
+    echo "  WARN: framework '$FRAMEWORK' not in frameworks/ registry — relying on Context7 only"
+  fi
+fi
+
+if [ "$VALIDATION_FAIL" = "true" ]; then
+  echo "=== VALIDATION FAILED — pipeline stopped ==="
+  exit 1
 fi
+echo "=== VALIDATION OK ==="
+
+# Detect if any value came from NL or default (i.e., not all explicit flags)
+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')")
+HAS_ANY_NL=$(echo "$RESOLVED" | node -e "const j=JSON.parse(require('fs').readFileSync(0,'utf8')); console.log(Object.values(j.resolved).some(v=>v.source==='NL') ? 'true' : 'false')")
+```
+
+**Confirmation checkpoint** (only in interactive mode):
+
+If `IS_AUTO=false` AND `ALL_FROM_FLAGS=false` (i.e., some values came from NL or defaults), the agent **MUST PAUSE** and ask the user to confirm before proceeding to scan/codebase-map/research stages.
+
+The pause is justified because:
+- NL detection can be wrong (e.g., wrong path inferred from a sentence)
+- All-defaults case may mean user is running from wrong cwd
+
+Format the confirmation prompt like this:
+
 ```
+The values above were resolved from {natural language | defaults | a mix of flags and NL}.
+Some values were not explicitly specified via flags.
+
+Do you want to continue with these inputs? (yes/no)
+- yes  → proceed with the pipeline
+- no   → cancel; re-run with explicit flags
+```
+
+**Skip the pause when:**
+- `IS_AUTO=true` (auto mode bypasses all safe checkpoints)
+- `ALL_FROM_FLAGS=true` (every resolved value has source: flag — user knows what they want)
 
-**If no --dev-repo provided**, use the current working directory:
+In auto mode, log instead of prompt:
+```
+Auto-mode: proceeding with detected inputs (banner above for audit trail).
+```
+
+Wait for user response before invoking any sub-agent. If user says "no" or anything other than yes/y/proceed/continue, STOP the pipeline cleanly:
 ```bash
-if [ -z "$DEV_REPO" ]; then
-  DEV_REPO=$(pwd)
-fi
+echo "Pipeline cancelled by user. No tokens spent on sub-agents."
+exit 0
 ```
 
+
+
 **Attempt to call qaa-tools init** (handle missing tool gracefully):
 ```bash
 INIT_JSON=$(node bin/qaa-tools.cjs init qa-start 2>/dev/null || echo "")
@@ -205,10 +367,35 @@ For **Option 1** (scan dev repo only):
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-scanner.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-scanner.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>Scan repository and produce SCAN_MANIFEST.md</objective>
-    <execution_context>@agents/qaa-scanner.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-scanner.md</execution_context>
     <files_to_read>
     - CLAUDE.md
+    - frameworks/*.json (read all framework registry entries for detection)
     </files_to_read>
     <parameters>
     dev_repo_path: {DEV_REPO}
@@ -223,10 +410,35 @@ For **Options 2 and 3** (scan both repos):
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-scanner.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-scanner.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>Scan both developer and QA repositories and produce SCAN_MANIFEST.md</objective>
-    <execution_context>@agents/qaa-scanner.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-scanner.md</execution_context>
     <files_to_read>
     - CLAUDE.md
+    - frameworks/*.json (read all framework registry entries for detection)
     </files_to_read>
     <parameters>
     dev_repo_path: {DEV_REPO}
@@ -271,9 +483,226 @@ If SCAN_MANIFEST.md is missing, treat as stage failure. Set status to failed and
 
 </step>
 
+<step name="codebase_map">
+
+## Step 3b: Codebase Map (Deep Analysis)
+
+**State update -- mark codebase-map as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Map Status" running --"Status" "Mapping codebase" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 1b: Codebase Mapper               |
+|  Status: Running 4 parallel sub-agents...|
++------------------------------------------+
+```
+
+**Create output directory:**
+```bash
+mkdir -p ${output_dir}/codebase
+```
+
+**Spawn 4 parallel sub-agents** (one per focus area). Issue all 4 `Agent()` calls in a single message for parallel execution:
+
+**Sub-agent 1 - testability focus** (produces TESTABILITY.md + TEST_SURFACE.md):
+```
+Agent(subagent_type="general-purpose",
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-codebase-mapper.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-codebase-mapper.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>Codebase analysis - testability focus. Produce TESTABILITY.md and TEST_SURFACE.md mapping what is testable in this codebase, mock boundaries, and exhaustive list of testable entry points.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-codebase-mapper.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ${output_dir}/SCAN_MANIFEST.md
+    </files_to_read>
+    <parameters>
+    focus_area: testability
+    dev_repo_path: {DEV_REPO}
+    output_dir: ${output_dir}/codebase
+    </parameters>
+  "
+)
+```
+
+**Sub-agent 2 - risk focus** (produces RISK_MAP.md + CRITICAL_PATHS.md):
+```
+Agent(subagent_type="general-purpose",
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-codebase-mapper.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-codebase-mapper.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>Codebase analysis - risk focus. Produce RISK_MAP.md and CRITICAL_PATHS.md identifying business-critical paths, security-sensitive areas, and the exact user flows that E2E smoke tests must cover.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-codebase-mapper.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ${output_dir}/SCAN_MANIFEST.md
+    </files_to_read>
+    <parameters>
+    focus_area: risk
+    dev_repo_path: {DEV_REPO}
+    output_dir: ${output_dir}/codebase
+    </parameters>
+  "
+)
+```
+
+**Sub-agent 3 - patterns focus** (produces CODE_PATTERNS.md + API_CONTRACTS.md):
+```
+Agent(subagent_type="general-purpose",
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-codebase-mapper.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-codebase-mapper.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>Codebase analysis - patterns focus. Produce CODE_PATTERNS.md and API_CONTRACTS.md documenting naming conventions, import style, and exact request/response shapes for API tests.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-codebase-mapper.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ${output_dir}/SCAN_MANIFEST.md
+    </files_to_read>
+    <parameters>
+    focus_area: patterns
+    dev_repo_path: {DEV_REPO}
+    output_dir: ${output_dir}/codebase
+    </parameters>
+  "
+)
+```
+
+**Sub-agent 4 - existing-tests focus** (produces TEST_ASSESSMENT.md + COVERAGE_GAPS.md):
+```
+Agent(subagent_type="general-purpose",
+  prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-codebase-mapper.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-codebase-mapper.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>Codebase analysis - existing-tests focus. Produce TEST_ASSESSMENT.md and COVERAGE_GAPS.md assessing current test quality, frameworks in use, and identifying which modules/functions/paths have no test coverage.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-codebase-mapper.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - ${output_dir}/SCAN_MANIFEST.md
+    </files_to_read>
+    <parameters>
+    focus_area: existing-tests
+    dev_repo_path: {DEV_REPO}
+    output_dir: ${output_dir}/codebase
+    </parameters>
+  "
+)
+```
+
+**Verify codebase docs exist:**
+```bash
+docs_count=$(ls ${output_dir}/codebase/*.md 2>/dev/null | wc -l)
+echo "Codebase docs produced: $docs_count of 8 expected"
+
+if [ "$docs_count" -eq 0 ]; then
+  echo "FAIL: No codebase docs produced. Pipeline continues with degraded context."
+  node bin/qaa-tools.cjs state patch --"Map Status" failed 2>/dev/null || true
+elif [ "$docs_count" -lt 4 ]; then
+  echo "WARNING: Fewer than 4 codebase docs produced. Downstream agents will have limited context."
+  node bin/qaa-tools.cjs state patch --"Map Status" "partial" 2>/dev/null || true
+else
+  echo "OK: codebase map sufficient ($docs_count docs)"
+  node bin/qaa-tools.cjs state patch --"Map Status" complete 2>/dev/null || true
+fi
+```
+
+**Codebase map is non-blocking:** if zero docs are produced, the pipeline continues with degraded context (downstream agents fall back to whatever they can find). All `<files_to_read>` references to codebase docs in subsequent stages use `(if exists)` semantics.
+
+</step>
+
 <step name="research">
 
-## Step 3b: Research Testing Ecosystem
+## Step 3c: Research Testing Ecosystem
 
 **State update -- mark research as running:**
 ```bash
@@ -283,7 +712,7 @@ node bin/qaa-tools.cjs state patch --"Research Status" running --"Status" "Resea
 **Print stage banner:**
 ```
 +------------------------------------------+
-|  STAGE 1b: Project Researcher            |
+|  STAGE 1c: Project Researcher            |
 |  Status: Running...                      |
 +------------------------------------------+
 ```
@@ -297,12 +726,44 @@ mkdir -p ${output_dir}/research
 ```
 Agent(subagent_type="general-purpose",
   prompt="
-    <objective>Research the testing ecosystem for this project. Use Context7 MCP as the primary source for all framework and library questions. Produce research documents consumed by downstream agents.</objective>
-    <execution_context>@agents/qaa-project-researcher.md</execution_context>
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-project-researcher.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-project-researcher.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>Research the testing ecosystem for this project. Use the codebase map findings (RISK_MAP, CODE_PATTERNS, API_CONTRACTS, TESTABILITY, etc., from ${output_dir}/codebase/) to ground your Context7 queries to the project specifics — query for the libraries/patterns the project actually uses (e.g., MSW integration, Stripe testing, OpenAPI contract testing) instead of generic framework questions. Use Context7 MCP as the primary source. Produce research documents consumed by downstream agents.</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-project-researcher.md</execution_context>
     <files_to_read>
     - CLAUDE.md
     - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
     - ${output_dir}/SCAN_MANIFEST.md
+    - ${output_dir}/codebase/TESTABILITY.md (if exists)
+    - ${output_dir}/codebase/TEST_SURFACE.md (if exists)
+    - ${output_dir}/codebase/RISK_MAP.md (if exists)
+    - ${output_dir}/codebase/CRITICAL_PATHS.md (if exists)
+    - ${output_dir}/codebase/CODE_PATTERNS.md (if exists)
+    - ${output_dir}/codebase/API_CONTRACTS.md (if exists)
+    - ${output_dir}/codebase/TEST_ASSESSMENT.md (if exists)
+    - ${output_dir}/codebase/COVERAGE_GAPS.md (if exists)
     </files_to_read>
     <parameters>
     mode: stack-testing
@@ -356,13 +817,41 @@ node bin/qaa-tools.cjs state patch --"Analyze Status" running --"Status" "Analyz
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-analyzer.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-analyzer.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>Analyze scanned repository and produce analysis artifacts</objective>
-    <execution_context>@agents/qaa-analyzer.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-analyzer.md</execution_context>
     <files_to_read>
     - {output_dir}/SCAN_MANIFEST.md
     - CLAUDE.md
     - {output_dir}/research/TESTING_STACK.md (if exists)
     - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - {output_dir}/codebase/RISK_MAP.md (if exists)
+    - {output_dir}/codebase/CRITICAL_PATHS.md (if exists)
+    - {output_dir}/codebase/TEST_ASSESSMENT.md (if exists)
+    - {output_dir}/codebase/COVERAGE_GAPS.md (if exists)
     </files_to_read>
     <parameters>
     mode: {mode}
@@ -445,8 +934,32 @@ node bin/qaa-tools.cjs state patch --"Status" "Injecting test IDs into frontend
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-testid-injector.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-testid-injector.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 and inject data-testid attributes into frontend components</objective>
-    <execution_context>@agents/qaa-testid-injector.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-testid-injector.md</execution_context>
     <files_to_read>
     - {output_dir}/SCAN_MANIFEST.md
     - CLAUDE.md
@@ -518,11 +1031,39 @@ node bin/qaa-tools.cjs state patch --"Generate Status" running --"Status" "Plann
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-planner.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-planner.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>Create test generation plan with task breakdown and dependencies</objective>
-    <execution_context>@agents/qaa-planner.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-planner.md</execution_context>
     <files_to_read>
     - {input files based on option}
     - CLAUDE.md
+    - {output_dir}/codebase/TESTABILITY.md (if exists)
+    - {output_dir}/codebase/TEST_SURFACE.md (if exists)
+    - {output_dir}/codebase/CRITICAL_PATHS.md (if exists)
+    - {output_dir}/codebase/COVERAGE_GAPS.md (if exists)
     </files_to_read>
     <parameters>
     workflow_option: {option}
@@ -584,15 +1125,43 @@ For each independent feature group from the generation plan, spawn a separate ex
 ```
 Agent(subagent_type="general-purpose",
   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 {feature} feature</objective>
-    <execution_context>@agents/qaa-executor.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-executor.md</execution_context>
     <files_to_read>
     - {output_dir}/GENERATION_PLAN.md
     - {output_dir}/TEST_INVENTORY.md (Option 1) or {output_dir}/GAP_ANALYSIS.md (Options 2/3)
     - CLAUDE.md
+    - frameworks/{detected_framework}.json (registry metadata for conventions, extensions, context7_keys)
     - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
     - {output_dir}/research/E2E_STRATEGY.md (if exists)
     - {output_dir}/research/API_TESTING_STRATEGY.md (if exists)
+    - {output_dir}/codebase/TEST_SURFACE.md (if exists)
+    - {output_dir}/codebase/CODE_PATTERNS.md (if exists)
+    - {output_dir}/codebase/API_CONTRACTS.md (if exists)
     </files_to_read>
     <parameters>
     workflow_option: {option}
@@ -613,15 +1182,43 @@ Spawn a single executor agent covering all tasks:
 ```
 Agent(subagent_type="general-purpose",
   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 all test files from generation plan</objective>
-    <execution_context>@agents/qaa-executor.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-executor.md</execution_context>
     <files_to_read>
     - {output_dir}/GENERATION_PLAN.md
     - {output_dir}/TEST_INVENTORY.md (Option 1) or {output_dir}/GAP_ANALYSIS.md (Options 2/3)
     - CLAUDE.md
+    - frameworks/{detected_framework}.json (registry metadata for conventions, extensions, context7_keys)
     - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
     - {output_dir}/research/E2E_STRATEGY.md (if exists)
     - {output_dir}/research/API_TESTING_STRATEGY.md (if exists)
+    - {output_dir}/codebase/TEST_SURFACE.md (if exists)
+    - {output_dir}/codebase/CODE_PATTERNS.md (if exists)
+    - {output_dir}/codebase/API_CONTRACTS.md (if exists)
     </files_to_read>
     <parameters>
     workflow_option: {option}
@@ -691,13 +1288,37 @@ node bin/qaa-tools.cjs state patch --"Validate Status" running --"Status" "Valid
 ```
 Agent(subagent_type="general-purpose",
   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>Run 4-layer validation on all generated test files</objective>
-    <execution_context>@agents/qaa-validator.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-validator.md</execution_context>
     <files_to_read>
     - {list all generated test files from executor return -- files_created paths}
     - {output_dir}/GENERATION_PLAN.md
     - CLAUDE.md
-    </files_to_read>
+    - frameworks/{detected_framework}.json (registry metadata for validation_commands)</files_to_read>
     <parameters>
     mode: validation
     max_fix_loops: 3
@@ -777,6 +1398,122 @@ Print: "Validation complete. Status: {overall_status}. Confidence: {confidence}.
 
 </step>
 
+<step name="e2e_runner">
+
+## Step 8b: E2E Runner (Conditional)
+
+**Condition:** Only execute if E2E test files were generated AND a live app URL is available:
+- `files_created` from the executor (Step 7) contains `*.e2e.*` / `*.cy.*` spec files, AND
+- `APP_URL` is set (`--app-url` flag or NL).
+
+**If no E2E files were generated:**
+Print: "Skipping E2E Runner (no E2E files generated)." → pipeline-summary E2E status = `skipped (no E2E files)`. Proceed to Step 9.
+
+**If no app URL is available:**
+Print: "Skipping E2E Runner (no app URL)." → pipeline-summary E2E status = `skipped (no app URL)`. Proceed to Step 9.
+
+**State update:**
+```bash
+node bin/qaa-tools.cjs state patch --"Status" "Running E2E tests against live app" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 6b: E2E Runner                    |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Spawn e2e-runner agent:**
+```
+Agent(subagent_type="general-purpose",
+  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 the generated E2E tests against the live application, capture real locators, fix mismatches, loop until pass or failures are classified. Query Context7 MCP to verify framework selector syntax before fixing locators. READ ~/.claude/qaa/MY_PREFERENCES.md FIRST — on this machine Cypress MUST be invoked with the `env -u ELECTRON_RUN_AS_NODE` prefix, and the app URL is PRODUCTION (read-only: never submit forms / create data).</objective>
+    <execution_context>~/.claude/qaa/agents/qaa-e2e-runner.md</execution_context>
+    <files_to_read>
+    - C:\Users\marti\.claude\CLAUDE.md
+    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
+    - ${output_dir}/locators/LOCATOR_REGISTRY.md (if exists)
+    - ${output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - ${output_dir}/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: {APP_URL}
+    output_dir: ${output_dir}
+    dev_repo_path: {DEV_REPO}
+    </parameters>
+  "
+)
+```
+
+**Parse e2e-runner return:**
+```
+E2E_RUNNER_COMPLETE:
+  app_url: "..."
+  total_tests: N
+  passed: N
+  failed: N
+  locator_fixes: N
+  app_bugs_found: N
+  fix_loops_used: N
+  runner_executed: true | false
+  runner_exit_code: N
+  runner_status: OK | BROKEN
+  report_path: "..."
+  screenshots: [...]
+```
+
+**Transition: validate → e2e-runner → { bug-detective | deliver | HALT }.**
+
+**HARD STOP on broken runner (#47/#48):** If the e2e-runner returns `runner_executed: false` (or `runner_status: BROKEN`, or an ENVIRONMENT ISSUE — e.g. Cypress not installed, binary cannot launch), the test runner could not execute. **HALT the pipeline** — do NOT advance to bug-detective and do NOT advance to deliver:
+```bash
+node bin/qaa-tools.cjs state patch --"Status" "Pipeline halted: E2E runner unavailable (env issue)" 2>/dev/null || true
+```
+- Set the pipeline-summary E2E Runner row to `halted (runner unavailable — env issue)`.
+- Print the halt banner (see Error Handling) and STOP. A DOM probe is NEVER accepted as a substitute for a real run; if the report presents probe evidence as "verified" while `runner_executed: false`, treat the run as INVALID.
+
+**Otherwise (`runner_executed: true`):**
+- Pipeline-summary E2E Runner status = `{passed}/{total_tests} passed ({fix_loops_used} fix loops)`.
+- If `app_bugs_found > 0`: surface the application bugs to the user (developer action required; the e2e-runner never modifies app code), then continue.
+- If `failed > 0` and `app_bugs_found == 0`: proceed to Step 9 (Bug Detective) for classification.
+- Else: proceed to Step 10 (Deliver).
+
+**Verify artifact exists:**
+```bash
+[ -f "${output_dir}/E2E_RUN_REPORT.md" ] && echo "OK" || echo "MISSING: E2E_RUN_REPORT.md"
+```
+
+Print: "E2E run complete. {passed}/{total_tests} passed. {locator_fixes} locators fixed. {app_bugs_found} app bugs found."
+
+</step>
+
 <step name="bug_detective">
 
 ## Step 9: Bug Detective (Conditional)
@@ -807,8 +1544,32 @@ node bin/qaa-tools.cjs state patch --"Status" "Classifying test failures" 2>/dev
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-bug-detective.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-bug-detective.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>Classify test failures and attempt auto-fixes for test errors. Use Playwright MCP to reproduce E2E failures in the browser when available.</objective>
-    <execution_context>@agents/qaa-bug-detective.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-bug-detective.md</execution_context>
     <files_to_read>
     - {test execution results -- from validator or direct test run}
     - {failing test source files -- paths from executor return}
@@ -1096,6 +1857,7 @@ node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null
     [{check}] Plan          -- {plan_result} ({file_count} files planned)
     [{check}] Generate      -- {generate_result} ({files_created} files created)
     [{check}] Validate      -- {validate_result} ({confidence} confidence)
+    [{check}] E2E Runner    -- {e2e_status}
     [{check}] Bug Detective -- {detective_result or 'skipped'}
     [{check}] Deliver       -- {deliver_result}
 
@@ -1231,8 +1993,32 @@ When resuming after a checkpoint, spawn a FRESH agent with explicit state:
 ```
 Agent(subagent_type="general-purpose",
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qa-pipeline-orchestrator.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/qa-pipeline-orchestrator.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>Continue QA pipeline from {stage} stage</objective>
-    <execution_context>@agents/qa-pipeline-orchestrator.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qa-pipeline-orchestrator.md</execution_context>
     <resume_context>
     Pipeline state:
     - Completed stages: {list of completed stages with their results}