qaa-agent 1.9.1 → 1.9.5

package/VERSION

@@ -0,0 +1 @@
+1.9.5

package/agents/qa-pipeline-orchestrator.md

@@ -6,13 +6,13 @@ skills:
 ---
 
 <purpose>
-Single orchestrator for the QA automation pipeline. Coordinates all 7 agent types (scanner, analyzer, planner, executor, validator, bug-detective, testid-injector) across 3 workflow options. Owns all pipeline state transitions -- agents never update state directly. The orchestrator sets stage status to 'running' before spawning an agent and 'complete' or 'failed' after the agent returns.
+Single orchestrator for the QA automation pipeline. Coordinates all 8 agent types (scanner, analyzer, planner, executor, validator, e2e-runner, bug-detective, testid-injector) across 3 workflow options. Owns all pipeline state transitions -- agents never update state directly. The orchestrator sets stage status to 'running' before spawning an agent and 'complete' or 'failed' after the agent returns.
 
 Invoked by the `/qa-start` slash command (Phase 6) or directly via Task() with this file as execution_context. Accepts 0-2 repo paths: 0 paths uses cwd as dev repo (Option 1), 1 path is dev-only (Option 1), 2 paths triggers maturity scoring to determine Option 2 or 3.
 
 **Pipeline stages in order:**
 ```
-scan -> codebase-map -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests] -> [bug-detective if failures] -> deliver
+scan -> codebase-map -> research -> analyze -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective if failures] -> deliver
 ```
 
 **Workflow options:**
@@ -116,7 +116,7 @@ Based on `option` value from init, select the stage sequence. Each option shares
 
 **Option 1 stages:**
 ```
-scan(dev) -> codebase-map -> analyze(full) -> [testid-inject if frontend] -> plan -> generate -> validate -> [bug-detective if failures] -> deliver
+scan(dev) -> codebase-map -> research -> analyze(full) -> [testid-inject if frontend] -> plan -> generate -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective if failures] -> deliver
 ```
 - Scanner: scan DEV repo only
 - Codebase Map: deep-scan codebase for testability, risk, patterns, existing tests
@@ -127,7 +127,7 @@ scan(dev) -> codebase-map -> analyze(full) -> [testid-inject if frontend] -> pla
 
 **Option 2 stages:**
 ```
-scan(both) -> codebase-map -> analyze(gap) -> [testid-inject if frontend] -> plan(gap) -> generate(gap) -> validate -> [bug-detective if failures] -> deliver
+scan(both) -> codebase-map -> research -> analyze(gap) -> [testid-inject if frontend] -> plan(gap) -> generate(gap) -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective if failures] -> deliver
 ```
 - Scanner: scan BOTH dev_repo_path and qa_repo_path
 - Codebase Map: deep-scan dev codebase for testability, risk, patterns, existing tests
@@ -138,7 +138,7 @@ scan(both) -> codebase-map -> analyze(gap) -> [testid-inject if frontend] -> pla
 
 **Option 3 stages:**
 ```
-scan(both) -> codebase-map -> analyze(gap) -> [testid-inject if frontend] -> plan(gap) -> generate(skip-existing) -> validate -> [bug-detective if failures] -> deliver
+scan(both) -> codebase-map -> research -> analyze(gap) -> [testid-inject if frontend] -> plan(gap) -> generate(skip-existing) -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective if failures] -> deliver
 ```
 - Scanner: scan BOTH dev_repo_path and qa_repo_path
 - Codebase Map: deep-scan dev codebase for testability, risk, patterns, existing tests
@@ -176,8 +176,32 @@ For **Option 1** -- scan DEV repo only:
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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
     </files_to_read>
@@ -194,8 +218,32 @@ For **Options 2 and 3** -- scan BOTH repos:
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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
     </files_to_read>
@@ -266,8 +314,32 @@ For each focus in [testability, risk, patterns, existing-tests]:
 
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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>Analyze codebase for QA purposes. Focus area: {focus}. Write documents to {output_dir}/codebase/.</objective>
-    <execution_context>@agents/qaa-codebase-mapper.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-codebase-mapper.md</execution_context>
     <files_to_read>
     - CLAUDE.md
     - {output_dir}/SCAN_MANIFEST.md
@@ -336,8 +408,32 @@ node bin/qaa-tools.cjs state patch --"Analyze Status" running --"Status" "Analyz
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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
@@ -413,8 +509,32 @@ node bin/qaa-tools.cjs state patch --"Status" "Injecting test IDs into frontend
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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
@@ -479,8 +599,32 @@ node bin/qaa-tools.cjs state patch --"Generate Status" running --"Status" "Plann
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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 -- see above}
     - CLAUDE.md
@@ -541,8 +685,32 @@ For each independent feature group from the generation plan, spawn a separate ex
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-executor.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-executor.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
     <objective>Generate test files for {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)
@@ -571,8 +739,32 @@ Spawn a single executor agent covering all tasks:
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-executor.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-executor.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
     <objective>Generate 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)
@@ -649,8 +841,32 @@ node bin/qaa-tools.cjs state patch --"Validate Status" running --"Status" "Valid
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-validator.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-validator.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
     <objective>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
@@ -723,8 +939,32 @@ node bin/qaa-tools.cjs state patch --"Status" "Running E2E tests against live ap
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-e2e-runner.md and adopt it as your operating contract.
+
+    Even though you may be running as a general-purpose agent (native subagent type
+    routing for QAA agents is not yet enabled), you MUST behave exactly as the
+    dedicated agent defined in that file: read everything in its <required_reading>,
+    obey its <quality_gate>, and run its mandatory bash checklist before returning.
+
+    Never modify application source code (src/, app/, lib/, or equivalent
+    directories) unless the agent's <scope> section explicitly permits it. If the
+    agent's contract restricts what files it can touch, honor that restriction —
+    even if a fix seems obvious or trivial.
+
+    If you cannot read ~/.claude/qaa/agents/qaa-e2e-runner.md (file missing, corrupted, parse
+    error), STOP and report the failure. Do NOT proceed with default agent
+    behavior — that defeats the purpose of this directive.
+
+    Do NOT improvise, substitute steps, apply changes the agent isn't allowed to
+    make, or skip any of the above. Skipping the agent's required_reading,
+    quality_gate, or bash checklist makes the run INVALID — its output cannot be
+    trusted.
+    </critical_directive>
+
     <objective>Run E2E tests against live application, capture real locators, fix mismatches, loop until pass</objective>
-    <execution_context>@agents/qaa-e2e-runner.md</execution_context>
+    <execution_context>~/.claude/qaa/agents/qaa-e2e-runner.md</execution_context>
     <files_to_read>
     - CLAUDE.md
     - {e2e_test_files from executor return}
@@ -751,11 +991,28 @@ E2E_RUNNER_COMPLETE:
   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: [...]
 ```
 
-Capture `passed`, `failed`, `app_bugs_found`, `locator_fixes` for pipeline summary.
+Capture `passed`, `failed`, `app_bugs_found`, `locator_fixes`, `runner_executed`, `runner_status` for pipeline summary.
+
+**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), 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)"
+```
+
+- Set the pipeline_summary E2E Runner row to `halted (runner unavailable — env issue)`.
+- Print the halt banner (see Error Handling).
+- 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`), continue with the normal flow below.
 
 If `app_bugs_found > 0`:
 Print: "E2E Runner found {app_bugs_found} application bug(s). See E2E_RUN_REPORT.md for details with screenshots."
@@ -797,8 +1054,32 @@ node bin/qaa-tools.cjs state patch --"Status" "Classifying test failures"
 ```
 Task(
   prompt="
+    <critical_directive priority="MANDATORY">
+    You are executing as a QAA pipeline agent. Your FIRST action MUST be to read
+    ~/.claude/qaa/agents/qaa-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</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}
@@ -821,9 +1102,14 @@ DETECTIVE_COMPLETE:
   classification_breakdown: {app_bug: N, test_error: N, env_issue: N, inconclusive: N}
   auto_fixes_applied: N
   auto_fixes_verified: N
+  runner_executed: true | false
+  runner_exit_code: N
+  runner_status: OK | BROKEN
   commit_hash: "..."
 ```
 
+**HARD STOP on broken runner (#47/#48):** If the bug-detective returns `runner_executed: false` / `runner_status: BROKEN` (the test suite never executed — ENV ISSUE), HALT the pipeline: do NOT advance to deliver, print the halt banner, and set Status to "Pipeline halted: test runner unavailable (env issue)". The bug-detective MUST NOT have substituted MCP DOM probes for a real run; a report claiming classifications with `runner_executed: false` is INVALID.
+
 **RISKY CHECKPOINT -- Application bugs detected:**
 
 If `classification_breakdown.app_bug > 0`:
@@ -1207,8 +1493,32 @@ When resuming after a checkpoint, spawn a FRESH agent (not serialized state). Th
 ```
 Task(
   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}
@@ -1326,6 +1636,7 @@ After all stages complete (or on pipeline stop), print a summary banner:
     [{check}] Plan         -- {plan_duration} ({file_count} files planned)
     [{check}] Generate     -- {generate_duration} ({files_created} files created)
     [{check}] Validate     -- {validate_duration} ({confidence} confidence)
+    [{check}] E2E Runner   -- {e2e_status}
     [{check}] Bug Detective-- {detective_duration or 'skipped'}
     [{check}] Deliver      -- {deliver_duration}
 
@@ -1343,6 +1654,8 @@ Where:
 - `[ ]` = stage skipped (testid-inject when no frontend, bug-detective when no failures)
 - `[!]` = stage failed
 
+`{e2e_status}` is one of: `skipped (no E2E files)`, `skipped (no app URL)`, `halted (runner unavailable — env issue)`, or `{e2e_duration}` on success. A `halted` status means the e2e-runner returned `runner_executed: false` / ENV ISSUE; the pipeline HALTs and does NOT advance to bug-detective or deliver (see #47/#48 transition).
+
 **On pipeline failure:** The summary still prints, but shows which stages completed and which failed, along with the failure reason.
 
 **Artifact list includes:**
@@ -1354,6 +1667,7 @@ Where:
 - GENERATION_PLAN.md (if plan stage completed)
 - Generated test files (if generate stage completed)
 - VALIDATION_REPORT.md (if validate stage completed)
+- E2E_RUN_REPORT.md (if e2e-runner ran)
 - FAILURE_CLASSIFICATION_REPORT.md (if bug detective ran)
 </pipeline_summary>
 
@@ -1363,12 +1677,13 @@ Where:
 Before this orchestrator is considered complete, verify:
 
 - [ ] All 3 workflow options route to correct stage sequences:
-  - Option 1: scan(dev) -> analyze(full) -> [testid-inject] -> plan -> generate -> validate -> [bug-detective] -> deliver
-  - Option 2: scan(both) -> analyze(gap) -> [testid-inject] -> plan(gap) -> generate(gap) -> validate -> [bug-detective] -> deliver
-  - Option 3: scan(both) -> analyze(gap) -> [testid-inject] -> plan(gap) -> generate(skip-existing) -> validate -> [bug-detective] -> deliver
+  - Option 1: scan(dev) -> codebase-map -> research -> analyze(full) -> [testid-inject] -> plan -> generate -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective] -> deliver
+  - Option 2: scan(both) -> codebase-map -> research -> analyze(gap) -> [testid-inject] -> plan(gap) -> generate(gap) -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective] -> deliver
+  - Option 3: scan(both) -> codebase-map -> research -> analyze(gap) -> [testid-inject] -> plan(gap) -> generate(skip-existing) -> validate -> [e2e-runner if E2E tests AND app URL] -> [bug-detective] -> deliver
 - [ ] Every agent spawn is bracketed by state updates (running before, complete/failed after)
 - [ ] Auto-advance correctly classifies safe vs risky checkpoints
 - [ ] Pipeline stops entirely on any stage failure (no partial PR)
+- [ ] e2e-runner / bug-detective transition enforced: `runner_executed: false` / `runner_status: BROKEN` / ENV ISSUE → HALT (no advance to bug-detective or deliver), never a fallback to DOM probes (validate → e2e-runner → { bug-detective | deliver | HALT })
 - [ ] Progress banners print for every stage even in auto mode
 - [ ] Deliver stage creates branch, commits per-stage, pushes, and creates draft PR via gh CLI
 - [ ] Resume spawns fresh agent with explicit state (no serialization)
@@ -1422,4 +1737,3 @@ echo "=== PIPELINE ORCHESTRATOR CHECKLIST END ==="
 - If any output shows a problem (STATE_FILE_NOT_FOUND, NO_SCAN_MANIFEST), fix it before returning.
 - If output shows expected "not found" results (e.g., NO_TESTID_REPORT when no frontend was detected), that is fine — the point is you RAN the command instead of assuming the answer.
 - Do NOT return control to the user until the block has been executed and you have read every line of output.
-

package/agents/qaa-analyzer.md

@@ -577,4 +577,3 @@ echo "=== ANALYZER CHECKLIST END ==="
 - If any output shows a problem (SCAN_MANIFEST_NOT_FOUND, OUTPUTS_NOT_WRITTEN), fix it before returning.
 - If output shows expected "not found" results (e.g., NO_CODEBASE_MAP when mapper hasn't run yet), that is fine — the point is you RAN the command instead of assuming the answer.
 - Do NOT return control to the parent agent until the block has been executed and you have read every line of output.
-