qaa-agent 1.9.2 → 1.9.5

package/workflows/qa-start.md

@@ -1,1405 +1,2048 @@
-<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.
-
-Invoked by the `/qa-start` slash command. Accepts `--dev-repo`, `--qa-repo`, and `--auto` flags.
-
-</purpose>
-
-<required_reading>
-
-Read these files BEFORE executing any pipeline stage. Do NOT skip.
-
-- **CLAUDE.md** -- Agent pipeline stages, module boundaries, quality gates, stage transitions, auto-advance rules, agent coordination, data-testid convention. Read the full file.
-- **agents/qa-pipeline-orchestrator.md** -- Full orchestrator logic, checkpoint classification, error handling, delivery sub-steps.
-
-</required_reading>
-
-<process>
-
-<step name="initialize" priority="first">
-
-## Step 1: Initialize Pipeline
-
-Parse `$ARGUMENTS` for flags:
-
-```bash
-DEV_REPO=""
-QA_REPO=""
-IS_AUTO=false
-
-# 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}')
-fi
-
-# 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}')
-fi
-
-# Parse --auto flag
-if echo "$ARGUMENTS" | grep -qE '\-\-auto'; then
-  IS_AUTO=true
-fi
-```
-
-**If no --dev-repo provided**, use the current working directory:
-```bash
-if [ -z "$DEV_REPO" ]; then
-  DEV_REPO=$(pwd)
-fi
-```
-
-**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 "")
-```
-
-If `INIT_JSON` is empty or the command fails, proceed with manual initialization:
-- Set `output_dir` to `.qa-output`
-- Set `date` to current date in `YYYY-MM-DD` format
-- Create output directory: `mkdir -p "$output_dir"`
-
-If `INIT_JSON` is valid, parse it for: `option`, `dev_repo_path`, `qa_repo_path`, `maturity_score`, `maturity_note`, `output_dir`, `date`, agent model assignments, `auto_advance`, `auto_chain_active`, `parallelization`, `commit_docs`.
-
-**Detect workflow option based on inputs:**
-
-- If `QA_REPO` is empty (no --qa-repo flag): **Option 1** (Dev-Only -- Full Pipeline)
-- If `QA_REPO` is provided: Assess QA repo maturity
-  - Check for existing test files, configs, coverage reports in QA repo
-  - Count test files, evaluate framework setup, check for CI config
-  - Score 0-100 based on test count, framework config presence, CI setup, coverage data
-  - Score >= 60: **Option 3** (Dev + Mature QA -- Surgical)
-  - Score < 60: **Option 2** (Dev + Immature QA -- Gap-Fill)
-
-**Determine auto-advance mode:**
-```bash
-# Check persistent config flag
-AUTO_CFG=$(node bin/qaa-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
-AUTO_CHAIN=$(node bin/qaa-tools.cjs config-get workflow._auto_chain_active 2>/dev/null || echo "false")
-
-if [ "$IS_AUTO" = "true" ] || [ "$AUTO_CFG" = "true" ] || [ "$AUTO_CHAIN" = "true" ]; then
-  IS_AUTO=true
-  node bin/qaa-tools.cjs config-set workflow._auto_chain_active true 2>/dev/null || true
-fi
-
-# Safety: clear stale chain flag if NOT in auto mode
-if [ "$IS_AUTO" = "false" ]; then
-  node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
-fi
-```
-
-**Print initialization banner:**
-```
-=== QA Pipeline Orchestrator ===
-Option: {option} ({description})
-Dev Repo: {DEV_REPO}
-QA Repo: {QA_REPO or 'N/A'}
-Maturity Score: {maturity_score or 'N/A'}
-Auto-Advance: {IS_AUTO}
-Date: {date}
-================================
-```
-
-Where `{description}` is:
-- Option 1: "Dev-Only -- Full Pipeline"
-- Option 2: "Dev + Immature QA -- Gap-Fill"
-- Option 3: "Dev + Mature QA -- Surgical"
-
-</step>
-
-<step name="detect_framework">
-
-## Step 2: Detect Framework
-
-Before scanning, detect the project's language and test framework to guide all downstream agents.
-
-**Read project config files:**
-```bash
-# Check for Node.js / JavaScript / TypeScript
-[ -f "${DEV_REPO}/package.json" ] && cat "${DEV_REPO}/package.json"
-
-# Check for Python
-[ -f "${DEV_REPO}/requirements.txt" ] && cat "${DEV_REPO}/requirements.txt"
-[ -f "${DEV_REPO}/pyproject.toml" ] && cat "${DEV_REPO}/pyproject.toml"
-[ -f "${DEV_REPO}/setup.py" ] && cat "${DEV_REPO}/setup.py"
-
-# Check for .NET
-ls "${DEV_REPO}"/*.csproj 2>/dev/null
-ls "${DEV_REPO}"/**/*.csproj 2>/dev/null
-
-# Check for Java
-[ -f "${DEV_REPO}/pom.xml" ] && echo "Maven project"
-[ -f "${DEV_REPO}/build.gradle" ] && echo "Gradle project"
-```
-
-**Detect test framework from config files:**
-```bash
-# JavaScript/TypeScript ecosystem
-[ -f "${DEV_REPO}/cypress.config.ts" ] || [ -f "${DEV_REPO}/cypress.config.js" ] && echo "FRAMEWORK=cypress"
-[ -f "${DEV_REPO}/playwright.config.ts" ] || [ -f "${DEV_REPO}/playwright.config.js" ] && echo "FRAMEWORK=playwright"
-[ -f "${DEV_REPO}/jest.config.ts" ] || [ -f "${DEV_REPO}/jest.config.js" ] && echo "FRAMEWORK=jest"
-[ -f "${DEV_REPO}/vitest.config.ts" ] || [ -f "${DEV_REPO}/vitest.config.js" ] && echo "FRAMEWORK=vitest"
-
-# Python ecosystem
-[ -f "${DEV_REPO}/pytest.ini" ] || [ -f "${DEV_REPO}/conftest.py" ] && echo "FRAMEWORK=pytest"
-
-# Check package.json devDependencies for test frameworks
-node -e "
-  try {
-    const pkg = require('${DEV_REPO}/package.json');
-    const deps = {...(pkg.devDependencies||{}), ...(pkg.dependencies||{})};
-    const frameworks = [];
-    if (deps.cypress) frameworks.push('cypress');
-    if (deps['@playwright/test'] || deps.playwright) frameworks.push('playwright');
-    if (deps.jest) frameworks.push('jest');
-    if (deps.vitest) frameworks.push('vitest');
-    if (deps.mocha) frameworks.push('mocha');
-    console.log(frameworks.join(',') || 'none');
-  } catch { console.log('no-package-json'); }
-" 2>/dev/null
-```
-
-**Assess detection confidence:**
-- **HIGH**: Config file found AND matching dependency in package.json/requirements.txt
-- **MEDIUM**: Only dependency found (no config file) OR only config file (no dependency)
-- **LOW**: No test framework detected, or conflicting signals
-
-**If no test framework found:**
-- If `IS_AUTO` is false: Ask the user which framework to use. STOP and wait for response.
-- If `IS_AUTO` is true: Select the most appropriate framework based on the project type:
-  - React/Next.js/Vue/Angular frontend -> Playwright
-  - Node.js API -> Jest or Vitest (prefer Vitest if ESM)
-  - Python -> Pytest
-  - Log: "Auto-selected: {framework} (no existing test framework detected)"
-
-**If detection confidence is LOW:**
-- If `IS_AUTO` is true: Auto-approve with most likely framework (SAFE checkpoint). Log: "Auto-approved: Framework detection (LOW confidence, selected {framework})". Continue.
-- If `IS_AUTO` is false: Present detection details to user. Wait for confirmation before proceeding.
-
-Store detected framework, language, and confidence for all downstream agents.
-
-</step>
-
-<step name="scan">
-
-## Step 3: Scan Repository
-
-**State update -- mark scan as running:**
-```bash
-node bin/qaa-tools.cjs state patch --"Scan Status" running --"Status" "Scanning repository" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 1: Scanner                        |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Spawn scanner agent:**
-
-For **Option 1** (scan dev repo only):
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Scan repository and produce SCAN_MANIFEST.md</objective>
-    <execution_context>@agents/qaa-scanner.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    dev_repo_path: {DEV_REPO}
-    qa_repo_path: null
-    output_path: {output_dir}/SCAN_MANIFEST.md
-    </parameters>
-  "
-)
-```
-
-For **Options 2 and 3** (scan both repos):
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Scan both developer and QA repositories and produce SCAN_MANIFEST.md</objective>
-    <execution_context>@agents/qaa-scanner.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    dev_repo_path: {DEV_REPO}
-    qa_repo_path: {QA_REPO}
-    output_path: {output_dir}/SCAN_MANIFEST.md
-    </parameters>
-  "
-)
-```
-
-**Parse scanner return:**
-
-Expected return structure:
-```
-SCANNER_COMPLETE:
-  file_path: ".qa-output/SCAN_MANIFEST.md"
-  decision: PROCEED | STOP
-  has_frontend: true | false
-  detection_confidence: HIGH | MEDIUM | LOW
-```
-
-**Handle decision field:**
-- If `decision` is `STOP`:
-  ```bash
-  node bin/qaa-tools.cjs state patch --"Scan Status" failed --"Status" "Pipeline stopped: Scanner returned STOP" 2>/dev/null || true
-  ```
-  Print failure banner and STOP PIPELINE ENTIRELY. Do NOT proceed to any further stage.
-
-- If `decision` is `PROCEED`:
-  ```bash
-  node bin/qaa-tools.cjs state patch --"Scan Status" complete 2>/dev/null || true
-  ```
-  Capture `has_frontend` for testid-injector conditional (Step 5).
-  Capture `detection_confidence` for checkpoint handling.
-
-**Verify artifact exists before continuing:**
-```bash
-[ -f "${output_dir}/SCAN_MANIFEST.md" ] && echo "OK: SCAN_MANIFEST.md exists" || echo "MISSING: SCAN_MANIFEST.md"
-```
-
-If SCAN_MANIFEST.md is missing, treat as stage failure. Set status to failed and STOP pipeline.
-
-</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="
-    <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>@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="
-    <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>@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="
-    <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>@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="
-    <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>@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 3c: Research Testing Ecosystem
-
-**State update -- mark research as running:**
-```bash
-node bin/qaa-tools.cjs state patch --"Research Status" running --"Status" "Researching testing ecosystem" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 1c: Project Researcher            |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Create output directory:**
-```bash
-mkdir -p ${output_dir}/research
-```
-
-**Spawn researcher agent:**
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <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>@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
-    dev_repo_path: {DEV_REPO}
-    output_dir: ${output_dir}/research
-    </parameters>
-  "
-)
-```
-
-**Verify research artifacts exist:**
-```bash
-ls ${output_dir}/research/*.md 2>/dev/null && echo "OK: Research files produced" || echo "WARNING: No research files produced"
-```
-
-**Research is non-blocking:** If the researcher fails or produces no output, the pipeline continues — downstream agents will fall back to Context7 queries directly. Log the warning but do NOT stop the pipeline.
-
-```bash
-if [ ! -f "${output_dir}/research/TESTING_STACK.md" ]; then
-  echo "WARNING: Research stage produced no output. Downstream agents will query Context7 directly."
-  node bin/qaa-tools.cjs state patch --"Research Status" "skipped (no output)" 2>/dev/null || true
-else
-  node bin/qaa-tools.cjs state patch --"Research Status" complete 2>/dev/null || true
-fi
-```
-
-</step>
-
-<step name="analyze">
-
-## Step 4: Analyze Repository
-
-**State update -- mark analyze as running:**
-```bash
-node bin/qaa-tools.cjs state patch --"Analyze Status" running --"Status" "Analyzing repository" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 2: Analyzer                       |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Determine analyzer mode based on option:**
-- Option 1: `mode = 'full'` (produces QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md)
-- Options 2 and 3: `mode = 'gap'` (produces GAP_ANALYSIS.md)
-
-**Spawn analyzer agent:**
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Analyze scanned repository and produce analysis artifacts</objective>
-    <execution_context>@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}
-    workflow_option: {option}
-    dev_repo_path: {DEV_REPO}
-    qa_repo_path: {QA_REPO or null}
-    output_path: {output_dir}/
-    </parameters>
-  "
-)
-```
-
-**Parse analyzer return:**
-
-Expected return structure:
-```
-ANALYZER_COMPLETE:
-  files_produced: [...]
-  total_test_count: N
-  pyramid_breakdown: {unit: N, integration: N, api: N, e2e: N}
-  risk_count: {high: N, medium: N, low: N}
-  commit_hash: "..."
-```
-
-Capture `files_produced`, `total_test_count`, `pyramid_breakdown` for downstream stages.
-
-**Handle analyzer checkpoint -- assumptions review:**
-- If `IS_AUTO` is true: Auto-approve all assumptions (SAFE checkpoint). Log: "Auto-approved: Analyzer assumptions". Continue pipeline.
-- If `IS_AUTO` is false: Present assumptions to user for review. Wait for confirmation or corrections. On user response, incorporate corrections and continue.
-
-**State update -- mark analyze as complete:**
-```bash
-node bin/qaa-tools.cjs state patch --"Analyze Status" complete 2>/dev/null || true
-```
-
-**Verify artifacts exist before continuing:**
-
-For Option 1:
-```bash
-[ -f "${output_dir}/QA_ANALYSIS.md" ] && echo "OK" || echo "MISSING: QA_ANALYSIS.md"
-[ -f "${output_dir}/TEST_INVENTORY.md" ] && echo "OK" || echo "MISSING: TEST_INVENTORY.md"
-```
-
-For Options 2/3:
-```bash
-[ -f "${output_dir}/GAP_ANALYSIS.md" ] && echo "OK" || echo "MISSING: GAP_ANALYSIS.md"
-```
-
-If required artifacts are missing, treat as stage failure. Set status to failed and STOP pipeline.
-
-Print: "Analysis complete. {total_test_count} test cases identified. Pyramid: unit={unit}, integration={integration}, api={api}, e2e={e2e}."
-
-</step>
-
-<step name="testid_inject">
-
-## Step 5: TestID Injection (Conditional)
-
-**Condition:** Only execute if `has_frontend` is `true` from scanner return (Step 3).
-
-**If `has_frontend` is false:**
-Print: "Skipping TestID injection (no frontend detected)." Proceed directly to Step 6 (Plan).
-
-**If `has_frontend` is true:**
-
-**State update:**
-```bash
-node bin/qaa-tools.cjs state patch --"Status" "Injecting test IDs into frontend components" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 3: TestID Injector                |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Spawn testid-injector agent:**
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Audit and inject data-testid attributes into frontend components</objective>
-    <execution_context>@agents/qaa-testid-injector.md</execution_context>
-    <files_to_read>
-    - {output_dir}/SCAN_MANIFEST.md
-    - CLAUDE.md
-    </files_to_read>
-    <parameters>
-    dev_repo_path: {DEV_REPO}
-    output_path: {output_dir}/TESTID_AUDIT_REPORT.md
-    </parameters>
-  "
-)
-```
-
-**Parse return:**
-
-Check for `INJECTOR_COMPLETE` vs `INJECTOR_SKIPPED`:
-
-If `INJECTOR_COMPLETE`:
-```
-INJECTOR_COMPLETE:
-  report_path: "..."
-  coverage_before: N%
-  coverage_after: N%
-  elements_injected: N
-  components_modified: N
-```
-Log: "TestID injection complete. Coverage: {coverage_before}% -> {coverage_after}%. {elements_injected} elements injected."
-
-If `INJECTOR_SKIPPED`:
-```
-INJECTOR_SKIPPED:
-  reason: "..."
-  action: "..."
-```
-Log the reason and continue pipeline.
-
-**Handle injector checkpoint -- audit review:**
-- If `IS_AUTO` is true: Auto-approve P0-only injection (SAFE checkpoint). Log: "Auto-approved: TestID injection (P0 elements only)". Continue pipeline.
-- If `IS_AUTO` is false: Present audit report to user. Wait for approval, element selection, or rejection. On user response, incorporate decisions and continue.
-
-**Verify artifact exists:**
-```bash
-[ -f "${output_dir}/TESTID_AUDIT_REPORT.md" ] && echo "OK" || echo "MISSING: TESTID_AUDIT_REPORT.md"
-```
-
-</step>
-
-<step name="plan">
-
-## Step 6: Plan Test Generation
-
-**State update -- mark generation as running (planning is part of generate):**
-```bash
-node bin/qaa-tools.cjs state patch --"Generate Status" running --"Status" "Planning test generation" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 4: Planner                        |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Determine planner input based on option:**
-- Option 1: Input from `{output_dir}/TEST_INVENTORY.md` + `{output_dir}/QA_ANALYSIS.md`
-- Options 2 and 3: Input from `{output_dir}/GAP_ANALYSIS.md`
-
-**Spawn planner agent:**
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Create test generation plan with task breakdown and dependencies</objective>
-    <execution_context>@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}
-    output_path: {output_dir}/GENERATION_PLAN.md
-    </parameters>
-  "
-)
-```
-
-**Parse planner return:**
-
-Expected return structure:
-```
-PLANNER_COMPLETE:
-  file_path: "..."
-  total_tasks: N
-  total_files: N
-  feature_count: N
-  dependency_depth: N
-  test_case_count: N
-  commit_hash: "..."
-```
-
-Capture `total_tasks`, `total_files`, `feature_count` for executor stage and pipeline summary.
-
-**Verify artifact exists:**
-```bash
-[ -f "${output_dir}/GENERATION_PLAN.md" ] && echo "OK" || echo "MISSING: GENERATION_PLAN.md"
-```
-
-If GENERATION_PLAN.md is missing, treat as stage failure. Set status to failed and STOP pipeline.
-
-Print: "Plan complete. {total_tasks} tasks, {total_files} files planned across {feature_count} features."
-
-</step>
-
-<step name="generate">
-
-## Step 7: Generate Test Files
-
-State update continues from planning (already set to `running` in Step 6).
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 5: Executor                       |
-|  Generating {total_files} test files     |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Determine execution strategy:**
-
-Check if planner created multiple independent feature groups. If `feature_count > 1` AND parallelization is enabled (from init config):
-
-**Parallel execution** (when feature_count > 1 and parallelization enabled):
-
-For each independent feature group from the generation plan, spawn a separate executor agent:
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Generate test files for {feature} feature</objective>
-    <execution_context>@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
-    - {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}
-    feature_group: {feature}
-    dev_repo_path: {DEV_REPO}
-    qa_repo_path: {QA_REPO or null}
-    output_path: {output_dir}/
-    </parameters>
-  "
-)
-```
-
-Multiple Agent() calls can be issued simultaneously for independent feature groups. Each executor handles one feature group and commits its files independently.
-
-**Sequential execution** (when feature_count == 1 or parallelization disabled):
-
-Spawn a single executor agent covering all tasks:
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Generate all test files from generation plan</objective>
-    <execution_context>@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
-    - {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}
-    dev_repo_path: {DEV_REPO}
-    qa_repo_path: {QA_REPO or null}
-    output_path: {output_dir}/
-    </parameters>
-  "
-)
-```
-
-**Option 3 specific -- skip existing tests:**
-
-For Option 3, pass `skip_existing_test_ids: true` to the executor so it checks existing test files by test ID before generating. If a test ID already exists in the QA repo, skip generating that test case:
-```
-<parameters>
-workflow_option: 3
-skip_existing_test_ids: true
-dev_repo_path: {DEV_REPO}
-qa_repo_path: {QA_REPO}
-output_path: {output_dir}/
-</parameters>
-```
-
-**Parse executor return:**
-
-Expected return structure:
-```
-EXECUTOR_COMPLETE:
-  files_created: [{path, type}, ...]
-  total_files: N
-  commit_count: N
-  features_covered: [...]
-  test_case_count: N
-```
-
-Capture `files_created`, `total_files`, `commit_count` for validation stage and pipeline summary.
-
-**State update -- mark generate as complete:**
-```bash
-node bin/qaa-tools.cjs state patch --"Generate Status" complete --"Status" "Test generation complete" 2>/dev/null || true
-```
-
-Print: "Generation complete. {total_files} files created across {features_covered_count} features. {commit_count} commits."
-
-</step>
-
-<step name="validate">
-
-## Step 8: Validate Generated Tests
-
-**State update -- mark validate as running:**
-```bash
-node bin/qaa-tools.cjs state patch --"Validate Status" running --"Status" "Validating generated tests" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 6: Validator                      |
-|  Validating {total_files} test files     |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Spawn validator agent:**
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Run 4-layer validation on all generated test files</objective>
-    <execution_context>@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>
-    <parameters>
-    mode: validation
-    max_fix_loops: 3
-    output_path: {output_dir}/VALIDATION_REPORT.md
-    </parameters>
-  "
-)
-```
-
-**4-layer validation:**
-1. **Syntax** -- File parses without errors
-2. **Structure** -- Follows POM rules, naming conventions, locator hierarchy
-3. **Dependencies** -- Imports resolve, fixtures exist, configs present
-4. **Logic** -- Assertions are concrete, test IDs are unique, no assertions in page objects
-
-**5. Browser verification (if app URL available and Playwright MCP connected):**
-
-After the 4-layer static validation, use Playwright MCP to verify E2E tests against the live app:
-
-1. Navigate to each page referenced in the E2E tests:
-   ```
-   mcp__playwright__browser_navigate({ url: "{app_url}/{route}" })
-   ```
-
-2. Take an accessibility snapshot to verify locators used in tests actually exist:
-   ```
-   mcp__playwright__browser_snapshot()
-   ```
-
-3. Cross-reference locators in generated tests against the real DOM:
-   - Verify `data-testid` values exist on the page
-   - Verify ARIA roles and names match test expectations
-   - Flag any test locator that does not match a real DOM element
-
-4. If mismatches are found, fix the test locators to match the real DOM and count as a fix loop iteration.
-
-This browser verification step prevents delivering tests with locators that will immediately fail at runtime.
-
-**Fix loop:** The validator automatically attempts to fix issues it finds. Maximum 3 fix loop iterations. After each fix attempt, re-validate.
-
-**Parse validator return:**
-
-Expected return structure:
-```
-VALIDATOR_COMPLETE:
-  report_path: "..."
-  overall_status: PASS | PASS_WITH_WARNINGS | FAIL
-  confidence: HIGH | MEDIUM | LOW
-  layers_summary: {syntax: PASS|FAIL, structure: PASS|FAIL, dependencies: PASS|FAIL, logic: PASS|FAIL}
-  fix_loops_used: N
-  issues_found: N
-  issues_fixed: N
-  unresolved_count: N
-```
-
-**RISKY CHECKPOINT -- Validator escalation:**
-
-If `unresolved_count > 0` after max fix loops (3):
-- **ALWAYS pause, even in auto mode** (RISKY checkpoint -- locked decision)
-- Present unresolved issues to user with full details from VALIDATION_REPORT.md
-- Wait for user decision:
-  - `"approve-with-warnings"`: Accept the validation with warnings. Set Validate Status to complete. Continue to deliver.
-  - `"abort"`: Set Validate Status to failed. STOP PIPELINE ENTIRELY.
-  - Manual guidance: User provides specific fix instructions. Spawn fresh continuation agent to apply fixes and re-validate.
-
-If `overall_status` is `PASS` or `PASS_WITH_WARNINGS` (and unresolved_count is 0):
-```bash
-node bin/qaa-tools.cjs state patch --"Validate Status" complete --"Status" "Validation passed" 2>/dev/null || true
-```
-
-**Verify artifact exists:**
-```bash
-[ -f "${output_dir}/VALIDATION_REPORT.md" ] && echo "OK" || echo "MISSING: VALIDATION_REPORT.md"
-```
-
-Print: "Validation complete. Status: {overall_status}. Confidence: {confidence}. {issues_found} issues found, {issues_fixed} fixed, {unresolved_count} unresolved."
-
-</step>
-
-<step name="bug_detective">
-
-## Step 9: Bug Detective (Conditional)
-
-**Condition:** Only execute if test failures were detected during validation. Check:
-- `overall_status === 'FAIL'` in validator return, OR
-- Generated tests have runtime failures that need classification
-
-**If no failures to classify:**
-Print: "Skipping Bug Detective (no test failures detected)." Proceed directly to Step 10 (Deliver).
-
-**If failures need classification:**
-
-**State update:**
-```bash
-node bin/qaa-tools.cjs state patch --"Status" "Classifying test failures" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 7: Bug Detective                  |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-**Spawn bug-detective agent:**
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <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>
-    <files_to_read>
-    - {test execution results -- from validator or direct test run}
-    - {failing test source files -- paths from executor return}
-    - CLAUDE.md
-    - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
-    - {output_dir}/research/TESTING_STACK.md (if exists)
-    </files_to_read>
-    <parameters>
-    output_path: {output_dir}/FAILURE_CLASSIFICATION_REPORT.md
-    app_url: {app_url if available}
-    </parameters>
-  "
-)
-```
-
-**Parse bug-detective return:**
-
-Expected return structure:
-```
-DETECTIVE_COMPLETE:
-  report_path: "..."
-  total_failures: N
-  classification_breakdown: {app_bug: N, test_error: N, env_issue: N, inconclusive: N}
-  auto_fixes_applied: N
-  auto_fixes_verified: N
-  commit_hash: "..."
-```
-
-**RISKY CHECKPOINT -- Application bugs detected:**
-
-If `classification_breakdown.app_bug > 0`:
-- **ALWAYS pause, even in auto mode** (RISKY checkpoint -- locked decision)
-- Present APPLICATION BUG classifications to user with full evidence from FAILURE_CLASSIFICATION_REPORT.md
-- These are genuine bugs in the application code discovered during test execution
-- The bug detective never touches application code -- it only reports
-- User must review and decide how to proceed:
-  - Acknowledge bugs and continue pipeline (bugs will be in the PR description for developer attention)
-  - Abort pipeline to fix bugs first
-
-**Verify artifact exists:**
-```bash
-[ -f "${output_dir}/FAILURE_CLASSIFICATION_REPORT.md" ] && echo "OK" || echo "MISSING: FAILURE_CLASSIFICATION_REPORT.md"
-```
-
-Print: "Bug Detective complete. {total_failures} failures classified: {app_bug} APP BUG, {test_error} TEST ERROR, {env_issue} ENV ISSUE, {inconclusive} INCONCLUSIVE. {auto_fixes_applied} auto-fixes applied."
-
-</step>
-
-<step name="deliver">
-
-## Step 10: Deliver
-
-**State update -- mark deliver as running:**
-```bash
-node bin/qaa-tools.cjs state patch --"Deliver Status" running --"Status" "Preparing delivery" 2>/dev/null || true
-```
-
-**Print stage banner:**
-```
-+------------------------------------------+
-|  STAGE 8: Deliver                        |
-|  Status: Running...                      |
-+------------------------------------------+
-```
-
-### Sub-step 1: Pre-flight checks
-
-**Check for git remote:**
-```bash
-REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
-```
-
-If `REMOTE_URL` is empty:
-- Print: "No git remote found. Artifacts committed locally but PR creation skipped."
-- Set `LOCAL_ONLY=true`
-
-**Check for gh CLI authentication:**
-```bash
-gh auth status 2>/dev/null
-```
-
-If `gh auth status` fails:
-- Print: "gh CLI not authenticated. Run 'gh auth login' first. Artifacts committed locally."
-- Set `LOCAL_ONLY=true`
-
-If both checks pass, set `LOCAL_ONLY=false`.
-
-### Sub-step 2: Derive project name
-
-```bash
-# Read from package.json
-PROJECT_NAME=$(node -e "try { const p = require('${DEV_REPO}/package.json'); console.log(p.name || ''); } catch { console.log(''); }" 2>/dev/null)
-
-# Fallback to directory basename
-if [ -z "$PROJECT_NAME" ]; then
-  PROJECT_NAME=$(basename "${DEV_REPO}")
-fi
-
-# Sanitize for branch naming
-PROJECT_NAME=$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')
-```
-
-### Sub-step 3: Detect default branch
-
-```bash
-DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
-```
-
-### Sub-step 4: Create feature branch
-
-```bash
-BRANCH="qa/auto-${PROJECT_NAME}-${date}"
-
-# Handle branch name collision
-if git rev-parse --verify "$BRANCH" 2>/dev/null || git rev-parse --verify "origin/$BRANCH" 2>/dev/null; then
-  SUFFIX=2
-  while git rev-parse --verify "${BRANCH}-${SUFFIX}" 2>/dev/null || git rev-parse --verify "origin/${BRANCH}-${SUFFIX}" 2>/dev/null; do
-    SUFFIX=$((SUFFIX + 1))
-  done
-  BRANCH="${BRANCH}-${SUFFIX}"
-fi
-
-git checkout -b "$BRANCH" "$DEFAULT_BRANCH"
-```
-
-### Sub-step 5: Per-stage atomic commits
-
-For each pipeline stage that produced artifacts, commit using `qaa-tools.cjs commit`. Check file existence before each commit.
-
-**Scanner:**
-```bash
-if [ -f "${output_dir}/SCAN_MANIFEST.md" ]; then
-  node bin/qaa-tools.cjs commit "qa(scanner): produce SCAN_MANIFEST.md for ${PROJECT_NAME}" --files ${output_dir}/SCAN_MANIFEST.md
-fi
-```
-
-**Analyzer (Option 1):**
-```bash
-if [ -f "${output_dir}/QA_ANALYSIS.md" ]; then
-  ANALYZER_FILES="${output_dir}/QA_ANALYSIS.md ${output_dir}/TEST_INVENTORY.md"
-  [ -f "${output_dir}/QA_REPO_BLUEPRINT.md" ] && ANALYZER_FILES="${ANALYZER_FILES} ${output_dir}/QA_REPO_BLUEPRINT.md"
-  node bin/qaa-tools.cjs commit "qa(analyzer): produce QA_ANALYSIS.md and TEST_INVENTORY.md" --files ${ANALYZER_FILES}
-fi
-```
-
-**Analyzer (Options 2/3):**
-```bash
-if [ -f "${output_dir}/GAP_ANALYSIS.md" ]; then
-  node bin/qaa-tools.cjs commit "qa(analyzer): produce GAP_ANALYSIS.md" --files ${output_dir}/GAP_ANALYSIS.md
-fi
-```
-
-**TestID Injector (if ran):**
-```bash
-if [ -f "${output_dir}/TESTID_AUDIT_REPORT.md" ]; then
-  node bin/qaa-tools.cjs commit "qa(testid-injector): inject ${elements_injected} data-testid attributes across ${components_modified} components" --files ${output_dir}/TESTID_AUDIT_REPORT.md ${modified_source_files}
-fi
-```
-
-**Executor:**
-```bash
-if [ -n "${generated_file_paths}" ]; then
-  node bin/qaa-tools.cjs commit "qa(executor): generate ${total_files} test files with POMs and fixtures" --files ${generated_file_paths}
-fi
-```
-
-**Planner:**
-```bash
-if [ -f "${output_dir}/GENERATION_PLAN.md" ]; then
-  node bin/qaa-tools.cjs commit "qa(planner): produce GENERATION_PLAN.md" --files ${output_dir}/GENERATION_PLAN.md
-fi
-```
-
-**Validator:**
-```bash
-if [ -f "${output_dir}/VALIDATION_REPORT.md" ]; then
-  node bin/qaa-tools.cjs commit "qa(validator): validate generated tests - ${overall_status} with ${confidence} confidence" --files ${output_dir}/VALIDATION_REPORT.md
-fi
-```
-
-**Bug Detective (if ran):**
-```bash
-if [ -f "${output_dir}/FAILURE_CLASSIFICATION_REPORT.md" ]; then
-  node bin/qaa-tools.cjs commit "qa(bug-detective): classify ${total_failures} failures - ${classification_summary}" --files ${output_dir}/FAILURE_CLASSIFICATION_REPORT.md
-fi
-```
-
-### Sub-step 6: Push branch
-
-If `LOCAL_ONLY` is true, skip this sub-step.
-
-```bash
-git push -u origin "$BRANCH"
-```
-
-If push fails:
-- Print: "Push failed: {error_message}. Artifacts committed locally on branch ${BRANCH}."
-- Set `LOCAL_ONLY=true`
-
-### Sub-step 7: Build PR body
-
-If `LOCAL_ONLY` is true, skip this sub-step.
-
-Read the PR template:
-```bash
-PR_BODY=$(cat templates/pr-template.md)
-```
-
-Replace all `{placeholder}` tokens with actual values collected during pipeline execution:
-- `{architecture_type}` -- from QA_ANALYSIS.md or SCAN_MANIFEST.md
-- `{framework}` -- detected test framework
-- `{risk_summary}` -- risk assessment counts (e.g., "3 HIGH, 5 MEDIUM, 2 LOW")
-- `{unit_count}` -- from pyramid_breakdown.unit
-- `{integration_count}` -- from pyramid_breakdown.integration
-- `{api_count}` -- from pyramid_breakdown.api
-- `{e2e_count}` -- from pyramid_breakdown.e2e
-- `{total_count}` -- from total_test_count
-- `{modules_covered}` -- count of modules with tests
-- `{coverage_estimate}` -- estimated coverage percentage
-- `{validation_result}` -- PASS, PASS_WITH_WARNINGS, or FAIL
-- `{confidence}` -- HIGH, MEDIUM, or LOW
-- `{fix_loops_used}` -- number 0-3
-- `{issues_found}` -- total issues found during validation
-- `{issues_fixed}` -- total issues auto-fixed
-- `{file_list}` -- if total files <= 50, list each file; if > 50, use summary
-
-### Sub-step 8: Create draft PR
-
-If `LOCAL_ONLY` is true, skip this sub-step.
-
-```bash
-PR_URL=$(gh pr create \
-  --draft \
-  --title "qa: automated test suite for ${PROJECT_NAME}" \
-  --body "${PR_BODY}" \
-  --label "qa-automation" \
-  --label "auto-generated" \
-  --assignee "@me" 2>&1)
-```
-
-Do NOT pass `--base` flag. Let gh auto-detect the default branch.
-
-On failure:
-- Print: "PR creation failed: ${PR_URL}. Artifacts remain on branch ${BRANCH}."
-- Do NOT stop the pipeline -- artifacts are committed and pushed.
-
-### Sub-step 9: Print result
-
-If PR was created successfully:
-```
-PR created: ${PR_URL}
-```
-
-If `LOCAL_ONLY` is true:
-```
-PR: not created (local-only mode). Artifacts committed on branch: ${BRANCH}
-```
-
-**State update -- mark deliver as complete:**
-```bash
-node bin/qaa-tools.cjs state patch --"Deliver Status" complete --"Status" "Pipeline complete" 2>/dev/null || true
-```
-
-**Clear auto-chain flag at pipeline completion:**
-```bash
-node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
-```
-
-### Print pipeline summary banner:
-
-```
-======================================================
-  QA PIPELINE COMPLETE
-======================================================
-
-  Option: {option} ({option_description})
-  Repository: {DEV_REPO}
-  QA Repo: {QA_REPO or 'N/A'}
-  Maturity Score: {maturity_score or 'N/A'}
-
-  Stages Completed:
-    [{check}] Scan          -- {scan_result}
-    [{check}] Analyze       -- {analyze_result} ({test_count} test cases)
-    [{check}] TestID Inject -- {inject_result or 'skipped'}
-    [{check}] Plan          -- {plan_result} ({file_count} files planned)
-    [{check}] Generate      -- {generate_result} ({files_created} files created)
-    [{check}] Validate      -- {validate_result} ({confidence} confidence)
-    [{check}] Bug Detective -- {detective_result or 'skipped'}
-    [{check}] Deliver       -- {deliver_result}
-
-  PR: {pr_url or 'not created (local-only)'}
-
-  Artifacts:
-    {list all produced .md files in output_dir}
-
-  Total Time: {total_duration}
-======================================================
-```
-
-Where: `[x]` = completed, `[ ]` = skipped, `[!]` = failed.
-
-</step>
-
-</process>
-
-<error_handling>
-
-## Error Handling
-
-### Stage Failure Protocol
-
-When any agent returns a failure or error:
-
-1. **Set stage status to failed:**
-   ```bash
-   node bin/qaa-tools.cjs state patch --"{Stage} Status" failed --"Status" "Pipeline stopped: {Stage} failed - {reason}" 2>/dev/null || true
-   ```
-
-2. **Print failure banner:**
-   ```
-   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-   !  PIPELINE STOPPED                        !
-   !  Stage: {stage_name}                     !
-   !  Reason: {failure_reason}                !
-   !                                          !
-   !  Completed: {completed_stages}           !
-   !  Artifacts: {artifacts_so_far}           !
-   !                                          !
-   !  Action required: Review and re-run      !
-   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
-   ```
-
-3. **DO NOT continue to next stage.** The pipeline stops entirely at the failed stage.
-
-4. **DO NOT create partial PR.** No branch, no commit, no PR with incomplete results.
-
-5. **Preserve all artifacts produced so far.** They remain on disk in `{output_dir}/` for debugging.
-
-### Artifact Verification
-
-After EVERY agent spawn, before advancing to next stage, verify the expected output artifact exists on disk:
-```bash
-[ -f "{expected_artifact_path}" ] && echo "OK" || echo "MISSING"
-```
-
-If artifacts are missing, treat as stage failure and STOP pipeline.
-
-### qaa-tools.cjs Graceful Fallback
-
-All `node bin/qaa-tools.cjs` calls use `2>/dev/null || true` to handle cases where the tool is not installed or not found. The pipeline must not break due to missing state management tooling -- it logs a warning and continues.
-
-</error_handling>
-
-<auto_advance>
-
-## Auto-Advance Mode
-
-Auto-advance is enabled when ANY of these is true:
-- `--auto` flag passed to the `/qa-start` invocation
-- `config.json` has `workflow.auto_advance = true` (persistent user preference)
-- `workflow._auto_chain_active = true` in config (ephemeral chain flag from ongoing auto run)
-
-### Behavior in Auto Mode
-
-**SAFE checkpoints are auto-approved.** The pipeline continues without pausing. A log message records the auto-approval:
-```
-Auto-approved: {checkpoint_description}
-```
-
-**RISKY checkpoints ALWAYS pause.** Even in auto mode, the pipeline stops and presents the checkpoint to the user.
-
-### Safe vs Risky Checkpoint Classification
-
-**SAFE (auto-approve in auto mode):**
-
-| Checkpoint | Agent | Auto-Action |
-|------------|-------|-------------|
-| Framework detection uncertain (LOW confidence) | Scanner | Approve with most likely framework |
-| Analyzer assumptions review | Analyzer | Approve all assumptions |
-| TestID audit review | TestID Injector | Approve P0-only injection |
-
-**RISKY (ALWAYS pause, even in auto mode):**
-
-| Checkpoint | Agent | User Action Required |
-|------------|-------|---------------------|
-| Validator escalation (unresolved issues after 3 fix loops) | Validator | approve-with-warnings, abort, or fix guidance |
-| APPLICATION BUG classification | Bug Detective | Review bugs, continue or fix first |
-| Any checkpoint with "unresolved" or "failed" blocking text | Any | Review specific blocking issue |
-
-### Checkpoint Handling Flow
-
-```
-On agent return with checkpoint data:
-  1. Extract checkpoint blocking field content
-  2. Classify as SAFE or RISKY:
-     - "framework detection" -> SAFE
-     - "assumptions" -> SAFE
-     - "audit" or "data-testid" -> SAFE
-     - "unresolved" -> RISKY
-     - "failed" -> RISKY
-     - "APPLICATION BUG" -> RISKY
-     - Default (no pattern match) -> RISKY (conservative)
-  3. If IS_AUTO and SAFE:
-     - Auto-approve with default action
-     - Log the auto-approval
-     - Continue pipeline
-  4. If IS_AUTO and RISKY:
-     - PAUSE pipeline
-     - Print checkpoint details with full context
-     - Wait for user input
-  5. If NOT auto (manual mode):
-     - PAUSE pipeline
-     - Print checkpoint details
-     - Wait for user input
-```
-
-### Resume After Checkpoint
-
-When resuming after a checkpoint, spawn a FRESH agent with explicit state:
-```
-Agent(subagent_type="general-purpose",
-  prompt="
-    <objective>Continue QA pipeline from {stage} stage</objective>
-    <execution_context>@agents/qa-pipeline-orchestrator.md</execution_context>
-    <resume_context>
-    Pipeline state:
-    - Completed stages: {list of completed stages with their results}
-    - Current stage: {stage that triggered checkpoint}
-    - Checkpoint response: {user's response or decision}
-    - Artifacts produced so far: {list of files with paths}
-
-    Resume from: {exact step in pipeline to resume from}
-    User decision: {what user chose at checkpoint}
-    </resume_context>
-  "
-)
-```
-
-### Stale Chain Flag Protection
-
-At orchestrator init, if `--auto` was NOT passed AND `auto_advance` config is false:
-```bash
-node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
-```
-
-At pipeline completion (success or failure):
-```bash
-node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
-```
-
-</auto_advance>
+<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 -> [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.
+
+</purpose>
+
+<required_reading>
+
+Read these files BEFORE executing any pipeline stage. Do NOT skip.
+
+- **CLAUDE.md** -- Agent pipeline stages, module boundaries, quality gates, stage transitions, auto-advance rules, agent coordination, data-testid convention. Read the full file.
+- **agents/qa-pipeline-orchestrator.md** -- Full orchestrator logic, checkpoint classification, error handling, delivery sub-steps.
+
+</required_reading>
+
+<process>
+
+<step name="initialize" priority="first">
+
+## Step 1: Initialize Pipeline
+
+Parse `$ARGUMENTS` using the intent detector (handles flags + natural language + paths with spaces):
+
+```bash
+# 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)"
+```
+
+**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):**
+
+```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
+
+# 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)
+
+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
+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 "")
+```
+
+If `INIT_JSON` is empty or the command fails, proceed with manual initialization:
+- Set `output_dir` to `.qa-output`
+- Set `date` to current date in `YYYY-MM-DD` format
+- Create output directory: `mkdir -p "$output_dir"`
+
+If `INIT_JSON` is valid, parse it for: `option`, `dev_repo_path`, `qa_repo_path`, `maturity_score`, `maturity_note`, `output_dir`, `date`, agent model assignments, `auto_advance`, `auto_chain_active`, `parallelization`, `commit_docs`.
+
+**Detect workflow option based on inputs:**
+
+- If `QA_REPO` is empty (no --qa-repo flag): **Option 1** (Dev-Only -- Full Pipeline)
+- If `QA_REPO` is provided: Assess QA repo maturity
+  - Check for existing test files, configs, coverage reports in QA repo
+  - Count test files, evaluate framework setup, check for CI config
+  - Score 0-100 based on test count, framework config presence, CI setup, coverage data
+  - Score >= 60: **Option 3** (Dev + Mature QA -- Surgical)
+  - Score < 60: **Option 2** (Dev + Immature QA -- Gap-Fill)
+
+**Determine auto-advance mode:**
+```bash
+# Check persistent config flag
+AUTO_CFG=$(node bin/qaa-tools.cjs config-get workflow.auto_advance 2>/dev/null || echo "false")
+AUTO_CHAIN=$(node bin/qaa-tools.cjs config-get workflow._auto_chain_active 2>/dev/null || echo "false")
+
+if [ "$IS_AUTO" = "true" ] || [ "$AUTO_CFG" = "true" ] || [ "$AUTO_CHAIN" = "true" ]; then
+  IS_AUTO=true
+  node bin/qaa-tools.cjs config-set workflow._auto_chain_active true 2>/dev/null || true
+fi
+
+# Safety: clear stale chain flag if NOT in auto mode
+if [ "$IS_AUTO" = "false" ]; then
+  node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
+fi
+```
+
+**Print initialization banner:**
+```
+=== QA Pipeline Orchestrator ===
+Option: {option} ({description})
+Dev Repo: {DEV_REPO}
+QA Repo: {QA_REPO or 'N/A'}
+Maturity Score: {maturity_score or 'N/A'}
+Auto-Advance: {IS_AUTO}
+Date: {date}
+================================
+```
+
+Where `{description}` is:
+- Option 1: "Dev-Only -- Full Pipeline"
+- Option 2: "Dev + Immature QA -- Gap-Fill"
+- Option 3: "Dev + Mature QA -- Surgical"
+
+</step>
+
+<step name="detect_framework">
+
+## Step 2: Detect Framework
+
+Before scanning, detect the project's language and test framework to guide all downstream agents.
+
+**Read project config files:**
+```bash
+# Check for Node.js / JavaScript / TypeScript
+[ -f "${DEV_REPO}/package.json" ] && cat "${DEV_REPO}/package.json"
+
+# Check for Python
+[ -f "${DEV_REPO}/requirements.txt" ] && cat "${DEV_REPO}/requirements.txt"
+[ -f "${DEV_REPO}/pyproject.toml" ] && cat "${DEV_REPO}/pyproject.toml"
+[ -f "${DEV_REPO}/setup.py" ] && cat "${DEV_REPO}/setup.py"
+
+# Check for .NET
+ls "${DEV_REPO}"/*.csproj 2>/dev/null
+ls "${DEV_REPO}"/**/*.csproj 2>/dev/null
+
+# Check for Java
+[ -f "${DEV_REPO}/pom.xml" ] && echo "Maven project"
+[ -f "${DEV_REPO}/build.gradle" ] && echo "Gradle project"
+```
+
+**Detect test framework from config files:**
+```bash
+# JavaScript/TypeScript ecosystem
+[ -f "${DEV_REPO}/cypress.config.ts" ] || [ -f "${DEV_REPO}/cypress.config.js" ] && echo "FRAMEWORK=cypress"
+[ -f "${DEV_REPO}/playwright.config.ts" ] || [ -f "${DEV_REPO}/playwright.config.js" ] && echo "FRAMEWORK=playwright"
+[ -f "${DEV_REPO}/jest.config.ts" ] || [ -f "${DEV_REPO}/jest.config.js" ] && echo "FRAMEWORK=jest"
+[ -f "${DEV_REPO}/vitest.config.ts" ] || [ -f "${DEV_REPO}/vitest.config.js" ] && echo "FRAMEWORK=vitest"
+
+# Python ecosystem
+[ -f "${DEV_REPO}/pytest.ini" ] || [ -f "${DEV_REPO}/conftest.py" ] && echo "FRAMEWORK=pytest"
+
+# Check package.json devDependencies for test frameworks
+node -e "
+  try {
+    const pkg = require('${DEV_REPO}/package.json');
+    const deps = {...(pkg.devDependencies||{}), ...(pkg.dependencies||{})};
+    const frameworks = [];
+    if (deps.cypress) frameworks.push('cypress');
+    if (deps['@playwright/test'] || deps.playwright) frameworks.push('playwright');
+    if (deps.jest) frameworks.push('jest');
+    if (deps.vitest) frameworks.push('vitest');
+    if (deps.mocha) frameworks.push('mocha');
+    console.log(frameworks.join(',') || 'none');
+  } catch { console.log('no-package-json'); }
+" 2>/dev/null
+```
+
+**Assess detection confidence:**
+- **HIGH**: Config file found AND matching dependency in package.json/requirements.txt
+- **MEDIUM**: Only dependency found (no config file) OR only config file (no dependency)
+- **LOW**: No test framework detected, or conflicting signals
+
+**If no test framework found:**
+- If `IS_AUTO` is false: Ask the user which framework to use. STOP and wait for response.
+- If `IS_AUTO` is true: Select the most appropriate framework based on the project type:
+  - React/Next.js/Vue/Angular frontend -> Playwright
+  - Node.js API -> Jest or Vitest (prefer Vitest if ESM)
+  - Python -> Pytest
+  - Log: "Auto-selected: {framework} (no existing test framework detected)"
+
+**If detection confidence is LOW:**
+- If `IS_AUTO` is true: Auto-approve with most likely framework (SAFE checkpoint). Log: "Auto-approved: Framework detection (LOW confidence, selected {framework})". Continue.
+- If `IS_AUTO` is false: Present detection details to user. Wait for confirmation before proceeding.
+
+Store detected framework, language, and confidence for all downstream agents.
+
+</step>
+
+<step name="scan">
+
+## Step 3: Scan Repository
+
+**State update -- mark scan as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Scan Status" running --"Status" "Scanning repository" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 1: Scanner                        |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Spawn scanner agent:**
+
+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>~/.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}
+    qa_repo_path: null
+    output_path: {output_dir}/SCAN_MANIFEST.md
+    </parameters>
+  "
+)
+```
+
+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>~/.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}
+    qa_repo_path: {QA_REPO}
+    output_path: {output_dir}/SCAN_MANIFEST.md
+    </parameters>
+  "
+)
+```
+
+**Parse scanner return:**
+
+Expected return structure:
+```
+SCANNER_COMPLETE:
+  file_path: ".qa-output/SCAN_MANIFEST.md"
+  decision: PROCEED | STOP
+  has_frontend: true | false
+  detection_confidence: HIGH | MEDIUM | LOW
+```
+
+**Handle decision field:**
+- If `decision` is `STOP`:
+  ```bash
+  node bin/qaa-tools.cjs state patch --"Scan Status" failed --"Status" "Pipeline stopped: Scanner returned STOP" 2>/dev/null || true
+  ```
+  Print failure banner and STOP PIPELINE ENTIRELY. Do NOT proceed to any further stage.
+
+- If `decision` is `PROCEED`:
+  ```bash
+  node bin/qaa-tools.cjs state patch --"Scan Status" complete 2>/dev/null || true
+  ```
+  Capture `has_frontend` for testid-injector conditional (Step 5).
+  Capture `detection_confidence` for checkpoint handling.
+
+**Verify artifact exists before continuing:**
+```bash
+[ -f "${output_dir}/SCAN_MANIFEST.md" ] && echo "OK: SCAN_MANIFEST.md exists" || echo "MISSING: SCAN_MANIFEST.md"
+```
+
+If SCAN_MANIFEST.md is missing, treat as stage failure. Set status to failed and STOP pipeline.
+
+</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 3c: Research Testing Ecosystem
+
+**State update -- mark research as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Research Status" running --"Status" "Researching testing ecosystem" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 1c: Project Researcher            |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Create output directory:**
+```bash
+mkdir -p ${output_dir}/research
+```
+
+**Spawn researcher 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-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
+    dev_repo_path: {DEV_REPO}
+    output_dir: ${output_dir}/research
+    </parameters>
+  "
+)
+```
+
+**Verify research artifacts exist:**
+```bash
+ls ${output_dir}/research/*.md 2>/dev/null && echo "OK: Research files produced" || echo "WARNING: No research files produced"
+```
+
+**Research is non-blocking:** If the researcher fails or produces no output, the pipeline continues — downstream agents will fall back to Context7 queries directly. Log the warning but do NOT stop the pipeline.
+
+```bash
+if [ ! -f "${output_dir}/research/TESTING_STACK.md" ]; then
+  echo "WARNING: Research stage produced no output. Downstream agents will query Context7 directly."
+  node bin/qaa-tools.cjs state patch --"Research Status" "skipped (no output)" 2>/dev/null || true
+else
+  node bin/qaa-tools.cjs state patch --"Research Status" complete 2>/dev/null || true
+fi
+```
+
+</step>
+
+<step name="analyze">
+
+## Step 4: Analyze Repository
+
+**State update -- mark analyze as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Analyze Status" running --"Status" "Analyzing repository" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 2: Analyzer                       |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Determine analyzer mode based on option:**
+- Option 1: `mode = 'full'` (produces QA_ANALYSIS.md + TEST_INVENTORY.md + QA_REPO_BLUEPRINT.md)
+- Options 2 and 3: `mode = 'gap'` (produces GAP_ANALYSIS.md)
+
+**Spawn analyzer 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-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>~/.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}
+    workflow_option: {option}
+    dev_repo_path: {DEV_REPO}
+    qa_repo_path: {QA_REPO or null}
+    output_path: {output_dir}/
+    </parameters>
+  "
+)
+```
+
+**Parse analyzer return:**
+
+Expected return structure:
+```
+ANALYZER_COMPLETE:
+  files_produced: [...]
+  total_test_count: N
+  pyramid_breakdown: {unit: N, integration: N, api: N, e2e: N}
+  risk_count: {high: N, medium: N, low: N}
+  commit_hash: "..."
+```
+
+Capture `files_produced`, `total_test_count`, `pyramid_breakdown` for downstream stages.
+
+**Handle analyzer checkpoint -- assumptions review:**
+- If `IS_AUTO` is true: Auto-approve all assumptions (SAFE checkpoint). Log: "Auto-approved: Analyzer assumptions". Continue pipeline.
+- If `IS_AUTO` is false: Present assumptions to user for review. Wait for confirmation or corrections. On user response, incorporate corrections and continue.
+
+**State update -- mark analyze as complete:**
+```bash
+node bin/qaa-tools.cjs state patch --"Analyze Status" complete 2>/dev/null || true
+```
+
+**Verify artifacts exist before continuing:**
+
+For Option 1:
+```bash
+[ -f "${output_dir}/QA_ANALYSIS.md" ] && echo "OK" || echo "MISSING: QA_ANALYSIS.md"
+[ -f "${output_dir}/TEST_INVENTORY.md" ] && echo "OK" || echo "MISSING: TEST_INVENTORY.md"
+```
+
+For Options 2/3:
+```bash
+[ -f "${output_dir}/GAP_ANALYSIS.md" ] && echo "OK" || echo "MISSING: GAP_ANALYSIS.md"
+```
+
+If required artifacts are missing, treat as stage failure. Set status to failed and STOP pipeline.
+
+Print: "Analysis complete. {total_test_count} test cases identified. Pyramid: unit={unit}, integration={integration}, api={api}, e2e={e2e}."
+
+</step>
+
+<step name="testid_inject">
+
+## Step 5: TestID Injection (Conditional)
+
+**Condition:** Only execute if `has_frontend` is `true` from scanner return (Step 3).
+
+**If `has_frontend` is false:**
+Print: "Skipping TestID injection (no frontend detected)." Proceed directly to Step 6 (Plan).
+
+**If `has_frontend` is true:**
+
+**State update:**
+```bash
+node bin/qaa-tools.cjs state patch --"Status" "Injecting test IDs into frontend components" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 3: TestID Injector                |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Spawn testid-injector 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-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>~/.claude/qaa/agents/qaa-testid-injector.md</execution_context>
+    <files_to_read>
+    - {output_dir}/SCAN_MANIFEST.md
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    dev_repo_path: {DEV_REPO}
+    output_path: {output_dir}/TESTID_AUDIT_REPORT.md
+    </parameters>
+  "
+)
+```
+
+**Parse return:**
+
+Check for `INJECTOR_COMPLETE` vs `INJECTOR_SKIPPED`:
+
+If `INJECTOR_COMPLETE`:
+```
+INJECTOR_COMPLETE:
+  report_path: "..."
+  coverage_before: N%
+  coverage_after: N%
+  elements_injected: N
+  components_modified: N
+```
+Log: "TestID injection complete. Coverage: {coverage_before}% -> {coverage_after}%. {elements_injected} elements injected."
+
+If `INJECTOR_SKIPPED`:
+```
+INJECTOR_SKIPPED:
+  reason: "..."
+  action: "..."
+```
+Log the reason and continue pipeline.
+
+**Handle injector checkpoint -- audit review:**
+- If `IS_AUTO` is true: Auto-approve P0-only injection (SAFE checkpoint). Log: "Auto-approved: TestID injection (P0 elements only)". Continue pipeline.
+- If `IS_AUTO` is false: Present audit report to user. Wait for approval, element selection, or rejection. On user response, incorporate decisions and continue.
+
+**Verify artifact exists:**
+```bash
+[ -f "${output_dir}/TESTID_AUDIT_REPORT.md" ] && echo "OK" || echo "MISSING: TESTID_AUDIT_REPORT.md"
+```
+
+</step>
+
+<step name="plan">
+
+## Step 6: Plan Test Generation
+
+**State update -- mark generation as running (planning is part of generate):**
+```bash
+node bin/qaa-tools.cjs state patch --"Generate Status" running --"Status" "Planning test generation" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 4: Planner                        |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Determine planner input based on option:**
+- Option 1: Input from `{output_dir}/TEST_INVENTORY.md` + `{output_dir}/QA_ANALYSIS.md`
+- Options 2 and 3: Input from `{output_dir}/GAP_ANALYSIS.md`
+
+**Spawn planner 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-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>~/.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}
+    output_path: {output_dir}/GENERATION_PLAN.md
+    </parameters>
+  "
+)
+```
+
+**Parse planner return:**
+
+Expected return structure:
+```
+PLANNER_COMPLETE:
+  file_path: "..."
+  total_tasks: N
+  total_files: N
+  feature_count: N
+  dependency_depth: N
+  test_case_count: N
+  commit_hash: "..."
+```
+
+Capture `total_tasks`, `total_files`, `feature_count` for executor stage and pipeline summary.
+
+**Verify artifact exists:**
+```bash
+[ -f "${output_dir}/GENERATION_PLAN.md" ] && echo "OK" || echo "MISSING: GENERATION_PLAN.md"
+```
+
+If GENERATION_PLAN.md is missing, treat as stage failure. Set status to failed and STOP pipeline.
+
+Print: "Plan complete. {total_tasks} tasks, {total_files} files planned across {feature_count} features."
+
+</step>
+
+<step name="generate">
+
+## Step 7: Generate Test Files
+
+State update continues from planning (already set to `running` in Step 6).
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 5: Executor                       |
+|  Generating {total_files} test files     |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Determine execution strategy:**
+
+Check if planner created multiple independent feature groups. If `feature_count > 1` AND parallelization is enabled (from init config):
+
+**Parallel execution** (when feature_count > 1 and parallelization enabled):
+
+For each independent feature group from the generation plan, spawn a separate executor 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-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>~/.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}
+    feature_group: {feature}
+    dev_repo_path: {DEV_REPO}
+    qa_repo_path: {QA_REPO or null}
+    output_path: {output_dir}/
+    </parameters>
+  "
+)
+```
+
+Multiple Agent() calls can be issued simultaneously for independent feature groups. Each executor handles one feature group and commits its files independently.
+
+**Sequential execution** (when feature_count == 1 or parallelization disabled):
+
+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>~/.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}
+    dev_repo_path: {DEV_REPO}
+    qa_repo_path: {QA_REPO or null}
+    output_path: {output_dir}/
+    </parameters>
+  "
+)
+```
+
+**Option 3 specific -- skip existing tests:**
+
+For Option 3, pass `skip_existing_test_ids: true` to the executor so it checks existing test files by test ID before generating. If a test ID already exists in the QA repo, skip generating that test case:
+```
+<parameters>
+workflow_option: 3
+skip_existing_test_ids: true
+dev_repo_path: {DEV_REPO}
+qa_repo_path: {QA_REPO}
+output_path: {output_dir}/
+</parameters>
+```
+
+**Parse executor return:**
+
+Expected return structure:
+```
+EXECUTOR_COMPLETE:
+  files_created: [{path, type}, ...]
+  total_files: N
+  commit_count: N
+  features_covered: [...]
+  test_case_count: N
+```
+
+Capture `files_created`, `total_files`, `commit_count` for validation stage and pipeline summary.
+
+**State update -- mark generate as complete:**
+```bash
+node bin/qaa-tools.cjs state patch --"Generate Status" complete --"Status" "Test generation complete" 2>/dev/null || true
+```
+
+Print: "Generation complete. {total_files} files created across {features_covered_count} features. {commit_count} commits."
+
+</step>
+
+<step name="validate">
+
+## Step 8: Validate Generated Tests
+
+**State update -- mark validate as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Validate Status" running --"Status" "Validating generated tests" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 6: Validator                      |
+|  Validating {total_files} test files     |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Spawn validator 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-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>~/.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
+    - frameworks/{detected_framework}.json (registry metadata for validation_commands)</files_to_read>
+    <parameters>
+    mode: validation
+    max_fix_loops: 3
+    output_path: {output_dir}/VALIDATION_REPORT.md
+    </parameters>
+  "
+)
+```
+
+**4-layer validation:**
+1. **Syntax** -- File parses without errors
+2. **Structure** -- Follows POM rules, naming conventions, locator hierarchy
+3. **Dependencies** -- Imports resolve, fixtures exist, configs present
+4. **Logic** -- Assertions are concrete, test IDs are unique, no assertions in page objects
+
+**5. Browser verification (if app URL available and Playwright MCP connected):**
+
+After the 4-layer static validation, use Playwright MCP to verify E2E tests against the live app:
+
+1. Navigate to each page referenced in the E2E tests:
+   ```
+   mcp__playwright__browser_navigate({ url: "{app_url}/{route}" })
+   ```
+
+2. Take an accessibility snapshot to verify locators used in tests actually exist:
+   ```
+   mcp__playwright__browser_snapshot()
+   ```
+
+3. Cross-reference locators in generated tests against the real DOM:
+   - Verify `data-testid` values exist on the page
+   - Verify ARIA roles and names match test expectations
+   - Flag any test locator that does not match a real DOM element
+
+4. If mismatches are found, fix the test locators to match the real DOM and count as a fix loop iteration.
+
+This browser verification step prevents delivering tests with locators that will immediately fail at runtime.
+
+**Fix loop:** The validator automatically attempts to fix issues it finds. Maximum 3 fix loop iterations. After each fix attempt, re-validate.
+
+**Parse validator return:**
+
+Expected return structure:
+```
+VALIDATOR_COMPLETE:
+  report_path: "..."
+  overall_status: PASS | PASS_WITH_WARNINGS | FAIL
+  confidence: HIGH | MEDIUM | LOW
+  layers_summary: {syntax: PASS|FAIL, structure: PASS|FAIL, dependencies: PASS|FAIL, logic: PASS|FAIL}
+  fix_loops_used: N
+  issues_found: N
+  issues_fixed: N
+  unresolved_count: N
+```
+
+**RISKY CHECKPOINT -- Validator escalation:**
+
+If `unresolved_count > 0` after max fix loops (3):
+- **ALWAYS pause, even in auto mode** (RISKY checkpoint -- locked decision)
+- Present unresolved issues to user with full details from VALIDATION_REPORT.md
+- Wait for user decision:
+  - `"approve-with-warnings"`: Accept the validation with warnings. Set Validate Status to complete. Continue to deliver.
+  - `"abort"`: Set Validate Status to failed. STOP PIPELINE ENTIRELY.
+  - Manual guidance: User provides specific fix instructions. Spawn fresh continuation agent to apply fixes and re-validate.
+
+If `overall_status` is `PASS` or `PASS_WITH_WARNINGS` (and unresolved_count is 0):
+```bash
+node bin/qaa-tools.cjs state patch --"Validate Status" complete --"Status" "Validation passed" 2>/dev/null || true
+```
+
+**Verify artifact exists:**
+```bash
+[ -f "${output_dir}/VALIDATION_REPORT.md" ] && echo "OK" || echo "MISSING: VALIDATION_REPORT.md"
+```
+
+Print: "Validation complete. Status: {overall_status}. Confidence: {confidence}. {issues_found} issues found, {issues_fixed} fixed, {unresolved_count} unresolved."
+
+</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)
+
+**Condition:** Only execute if test failures were detected during validation. Check:
+- `overall_status === 'FAIL'` in validator return, OR
+- Generated tests have runtime failures that need classification
+
+**If no failures to classify:**
+Print: "Skipping Bug Detective (no test failures detected)." Proceed directly to Step 10 (Deliver).
+
+**If failures need classification:**
+
+**State update:**
+```bash
+node bin/qaa-tools.cjs state patch --"Status" "Classifying test failures" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 7: Bug Detective                  |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+**Spawn bug-detective 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-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>~/.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}
+    - CLAUDE.md
+    - {output_dir}/research/FRAMEWORK_CAPABILITIES.md (if exists)
+    - {output_dir}/research/TESTING_STACK.md (if exists)
+    </files_to_read>
+    <parameters>
+    output_path: {output_dir}/FAILURE_CLASSIFICATION_REPORT.md
+    app_url: {app_url if available}
+    </parameters>
+  "
+)
+```
+
+**Parse bug-detective return:**
+
+Expected return structure:
+```
+DETECTIVE_COMPLETE:
+  report_path: "..."
+  total_failures: N
+  classification_breakdown: {app_bug: N, test_error: N, env_issue: N, inconclusive: N}
+  auto_fixes_applied: N
+  auto_fixes_verified: N
+  commit_hash: "..."
+```
+
+**RISKY CHECKPOINT -- Application bugs detected:**
+
+If `classification_breakdown.app_bug > 0`:
+- **ALWAYS pause, even in auto mode** (RISKY checkpoint -- locked decision)
+- Present APPLICATION BUG classifications to user with full evidence from FAILURE_CLASSIFICATION_REPORT.md
+- These are genuine bugs in the application code discovered during test execution
+- The bug detective never touches application code -- it only reports
+- User must review and decide how to proceed:
+  - Acknowledge bugs and continue pipeline (bugs will be in the PR description for developer attention)
+  - Abort pipeline to fix bugs first
+
+**Verify artifact exists:**
+```bash
+[ -f "${output_dir}/FAILURE_CLASSIFICATION_REPORT.md" ] && echo "OK" || echo "MISSING: FAILURE_CLASSIFICATION_REPORT.md"
+```
+
+Print: "Bug Detective complete. {total_failures} failures classified: {app_bug} APP BUG, {test_error} TEST ERROR, {env_issue} ENV ISSUE, {inconclusive} INCONCLUSIVE. {auto_fixes_applied} auto-fixes applied."
+
+</step>
+
+<step name="deliver">
+
+## Step 10: Deliver
+
+**State update -- mark deliver as running:**
+```bash
+node bin/qaa-tools.cjs state patch --"Deliver Status" running --"Status" "Preparing delivery" 2>/dev/null || true
+```
+
+**Print stage banner:**
+```
++------------------------------------------+
+|  STAGE 8: Deliver                        |
+|  Status: Running...                      |
++------------------------------------------+
+```
+
+### Sub-step 1: Pre-flight checks
+
+**Check for git remote:**
+```bash
+REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
+```
+
+If `REMOTE_URL` is empty:
+- Print: "No git remote found. Artifacts committed locally but PR creation skipped."
+- Set `LOCAL_ONLY=true`
+
+**Check for gh CLI authentication:**
+```bash
+gh auth status 2>/dev/null
+```
+
+If `gh auth status` fails:
+- Print: "gh CLI not authenticated. Run 'gh auth login' first. Artifacts committed locally."
+- Set `LOCAL_ONLY=true`
+
+If both checks pass, set `LOCAL_ONLY=false`.
+
+### Sub-step 2: Derive project name
+
+```bash
+# Read from package.json
+PROJECT_NAME=$(node -e "try { const p = require('${DEV_REPO}/package.json'); console.log(p.name || ''); } catch { console.log(''); }" 2>/dev/null)
+
+# Fallback to directory basename
+if [ -z "$PROJECT_NAME" ]; then
+  PROJECT_NAME=$(basename "${DEV_REPO}")
+fi
+
+# Sanitize for branch naming
+PROJECT_NAME=$(echo "$PROJECT_NAME" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//' | sed 's/-$//')
+```
+
+### Sub-step 3: Detect default branch
+
+```bash
+DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null || echo "main")
+```
+
+### Sub-step 4: Create feature branch
+
+```bash
+BRANCH="qa/auto-${PROJECT_NAME}-${date}"
+
+# Handle branch name collision
+if git rev-parse --verify "$BRANCH" 2>/dev/null || git rev-parse --verify "origin/$BRANCH" 2>/dev/null; then
+  SUFFIX=2
+  while git rev-parse --verify "${BRANCH}-${SUFFIX}" 2>/dev/null || git rev-parse --verify "origin/${BRANCH}-${SUFFIX}" 2>/dev/null; do
+    SUFFIX=$((SUFFIX + 1))
+  done
+  BRANCH="${BRANCH}-${SUFFIX}"
+fi
+
+git checkout -b "$BRANCH" "$DEFAULT_BRANCH"
+```
+
+### Sub-step 5: Per-stage atomic commits
+
+For each pipeline stage that produced artifacts, commit using `qaa-tools.cjs commit`. Check file existence before each commit.
+
+**Scanner:**
+```bash
+if [ -f "${output_dir}/SCAN_MANIFEST.md" ]; then
+  node bin/qaa-tools.cjs commit "qa(scanner): produce SCAN_MANIFEST.md for ${PROJECT_NAME}" --files ${output_dir}/SCAN_MANIFEST.md
+fi
+```
+
+**Analyzer (Option 1):**
+```bash
+if [ -f "${output_dir}/QA_ANALYSIS.md" ]; then
+  ANALYZER_FILES="${output_dir}/QA_ANALYSIS.md ${output_dir}/TEST_INVENTORY.md"
+  [ -f "${output_dir}/QA_REPO_BLUEPRINT.md" ] && ANALYZER_FILES="${ANALYZER_FILES} ${output_dir}/QA_REPO_BLUEPRINT.md"
+  node bin/qaa-tools.cjs commit "qa(analyzer): produce QA_ANALYSIS.md and TEST_INVENTORY.md" --files ${ANALYZER_FILES}
+fi
+```
+
+**Analyzer (Options 2/3):**
+```bash
+if [ -f "${output_dir}/GAP_ANALYSIS.md" ]; then
+  node bin/qaa-tools.cjs commit "qa(analyzer): produce GAP_ANALYSIS.md" --files ${output_dir}/GAP_ANALYSIS.md
+fi
+```
+
+**TestID Injector (if ran):**
+```bash
+if [ -f "${output_dir}/TESTID_AUDIT_REPORT.md" ]; then
+  node bin/qaa-tools.cjs commit "qa(testid-injector): inject ${elements_injected} data-testid attributes across ${components_modified} components" --files ${output_dir}/TESTID_AUDIT_REPORT.md ${modified_source_files}
+fi
+```
+
+**Executor:**
+```bash
+if [ -n "${generated_file_paths}" ]; then
+  node bin/qaa-tools.cjs commit "qa(executor): generate ${total_files} test files with POMs and fixtures" --files ${generated_file_paths}
+fi
+```
+
+**Planner:**
+```bash
+if [ -f "${output_dir}/GENERATION_PLAN.md" ]; then
+  node bin/qaa-tools.cjs commit "qa(planner): produce GENERATION_PLAN.md" --files ${output_dir}/GENERATION_PLAN.md
+fi
+```
+
+**Validator:**
+```bash
+if [ -f "${output_dir}/VALIDATION_REPORT.md" ]; then
+  node bin/qaa-tools.cjs commit "qa(validator): validate generated tests - ${overall_status} with ${confidence} confidence" --files ${output_dir}/VALIDATION_REPORT.md
+fi
+```
+
+**Bug Detective (if ran):**
+```bash
+if [ -f "${output_dir}/FAILURE_CLASSIFICATION_REPORT.md" ]; then
+  node bin/qaa-tools.cjs commit "qa(bug-detective): classify ${total_failures} failures - ${classification_summary}" --files ${output_dir}/FAILURE_CLASSIFICATION_REPORT.md
+fi
+```
+
+### Sub-step 6: Push branch
+
+If `LOCAL_ONLY` is true, skip this sub-step.
+
+```bash
+git push -u origin "$BRANCH"
+```
+
+If push fails:
+- Print: "Push failed: {error_message}. Artifacts committed locally on branch ${BRANCH}."
+- Set `LOCAL_ONLY=true`
+
+### Sub-step 7: Build PR body
+
+If `LOCAL_ONLY` is true, skip this sub-step.
+
+Read the PR template:
+```bash
+PR_BODY=$(cat templates/pr-template.md)
+```
+
+Replace all `{placeholder}` tokens with actual values collected during pipeline execution:
+- `{architecture_type}` -- from QA_ANALYSIS.md or SCAN_MANIFEST.md
+- `{framework}` -- detected test framework
+- `{risk_summary}` -- risk assessment counts (e.g., "3 HIGH, 5 MEDIUM, 2 LOW")
+- `{unit_count}` -- from pyramid_breakdown.unit
+- `{integration_count}` -- from pyramid_breakdown.integration
+- `{api_count}` -- from pyramid_breakdown.api
+- `{e2e_count}` -- from pyramid_breakdown.e2e
+- `{total_count}` -- from total_test_count
+- `{modules_covered}` -- count of modules with tests
+- `{coverage_estimate}` -- estimated coverage percentage
+- `{validation_result}` -- PASS, PASS_WITH_WARNINGS, or FAIL
+- `{confidence}` -- HIGH, MEDIUM, or LOW
+- `{fix_loops_used}` -- number 0-3
+- `{issues_found}` -- total issues found during validation
+- `{issues_fixed}` -- total issues auto-fixed
+- `{file_list}` -- if total files <= 50, list each file; if > 50, use summary
+
+### Sub-step 8: Create draft PR
+
+If `LOCAL_ONLY` is true, skip this sub-step.
+
+```bash
+PR_URL=$(gh pr create \
+  --draft \
+  --title "qa: automated test suite for ${PROJECT_NAME}" \
+  --body "${PR_BODY}" \
+  --label "qa-automation" \
+  --label "auto-generated" \
+  --assignee "@me" 2>&1)
+```
+
+Do NOT pass `--base` flag. Let gh auto-detect the default branch.
+
+On failure:
+- Print: "PR creation failed: ${PR_URL}. Artifacts remain on branch ${BRANCH}."
+- Do NOT stop the pipeline -- artifacts are committed and pushed.
+
+### Sub-step 9: Print result
+
+If PR was created successfully:
+```
+PR created: ${PR_URL}
+```
+
+If `LOCAL_ONLY` is true:
+```
+PR: not created (local-only mode). Artifacts committed on branch: ${BRANCH}
+```
+
+**State update -- mark deliver as complete:**
+```bash
+node bin/qaa-tools.cjs state patch --"Deliver Status" complete --"Status" "Pipeline complete" 2>/dev/null || true
+```
+
+**Clear auto-chain flag at pipeline completion:**
+```bash
+node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
+```
+
+### Print pipeline summary banner:
+
+```
+======================================================
+  QA PIPELINE COMPLETE
+======================================================
+
+  Option: {option} ({option_description})
+  Repository: {DEV_REPO}
+  QA Repo: {QA_REPO or 'N/A'}
+  Maturity Score: {maturity_score or 'N/A'}
+
+  Stages Completed:
+    [{check}] Scan          -- {scan_result}
+    [{check}] Analyze       -- {analyze_result} ({test_count} test cases)
+    [{check}] TestID Inject -- {inject_result or 'skipped'}
+    [{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}
+
+  PR: {pr_url or 'not created (local-only)'}
+
+  Artifacts:
+    {list all produced .md files in output_dir}
+
+  Total Time: {total_duration}
+======================================================
+```
+
+Where: `[x]` = completed, `[ ]` = skipped, `[!]` = failed.
+
+</step>
+
+</process>
+
+<error_handling>
+
+## Error Handling
+
+### Stage Failure Protocol
+
+When any agent returns a failure or error:
+
+1. **Set stage status to failed:**
+   ```bash
+   node bin/qaa-tools.cjs state patch --"{Stage} Status" failed --"Status" "Pipeline stopped: {Stage} failed - {reason}" 2>/dev/null || true
+   ```
+
+2. **Print failure banner:**
+   ```
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   !  PIPELINE STOPPED                        !
+   !  Stage: {stage_name}                     !
+   !  Reason: {failure_reason}                !
+   !                                          !
+   !  Completed: {completed_stages}           !
+   !  Artifacts: {artifacts_so_far}           !
+   !                                          !
+   !  Action required: Review and re-run      !
+   !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+   ```
+
+3. **DO NOT continue to next stage.** The pipeline stops entirely at the failed stage.
+
+4. **DO NOT create partial PR.** No branch, no commit, no PR with incomplete results.
+
+5. **Preserve all artifacts produced so far.** They remain on disk in `{output_dir}/` for debugging.
+
+### Artifact Verification
+
+After EVERY agent spawn, before advancing to next stage, verify the expected output artifact exists on disk:
+```bash
+[ -f "{expected_artifact_path}" ] && echo "OK" || echo "MISSING"
+```
+
+If artifacts are missing, treat as stage failure and STOP pipeline.
+
+### qaa-tools.cjs Graceful Fallback
+
+All `node bin/qaa-tools.cjs` calls use `2>/dev/null || true` to handle cases where the tool is not installed or not found. The pipeline must not break due to missing state management tooling -- it logs a warning and continues.
+
+</error_handling>
+
+<auto_advance>
+
+## Auto-Advance Mode
+
+Auto-advance is enabled when ANY of these is true:
+- `--auto` flag passed to the `/qa-start` invocation
+- `config.json` has `workflow.auto_advance = true` (persistent user preference)
+- `workflow._auto_chain_active = true` in config (ephemeral chain flag from ongoing auto run)
+
+### Behavior in Auto Mode
+
+**SAFE checkpoints are auto-approved.** The pipeline continues without pausing. A log message records the auto-approval:
+```
+Auto-approved: {checkpoint_description}
+```
+
+**RISKY checkpoints ALWAYS pause.** Even in auto mode, the pipeline stops and presents the checkpoint to the user.
+
+### Safe vs Risky Checkpoint Classification
+
+**SAFE (auto-approve in auto mode):**
+
+| Checkpoint | Agent | Auto-Action |
+|------------|-------|-------------|
+| Framework detection uncertain (LOW confidence) | Scanner | Approve with most likely framework |
+| Analyzer assumptions review | Analyzer | Approve all assumptions |
+| TestID audit review | TestID Injector | Approve P0-only injection |
+
+**RISKY (ALWAYS pause, even in auto mode):**
+
+| Checkpoint | Agent | User Action Required |
+|------------|-------|---------------------|
+| Validator escalation (unresolved issues after 3 fix loops) | Validator | approve-with-warnings, abort, or fix guidance |
+| APPLICATION BUG classification | Bug Detective | Review bugs, continue or fix first |
+| Any checkpoint with "unresolved" or "failed" blocking text | Any | Review specific blocking issue |
+
+### Checkpoint Handling Flow
+
+```
+On agent return with checkpoint data:
+  1. Extract checkpoint blocking field content
+  2. Classify as SAFE or RISKY:
+     - "framework detection" -> SAFE
+     - "assumptions" -> SAFE
+     - "audit" or "data-testid" -> SAFE
+     - "unresolved" -> RISKY
+     - "failed" -> RISKY
+     - "APPLICATION BUG" -> RISKY
+     - Default (no pattern match) -> RISKY (conservative)
+  3. If IS_AUTO and SAFE:
+     - Auto-approve with default action
+     - Log the auto-approval
+     - Continue pipeline
+  4. If IS_AUTO and RISKY:
+     - PAUSE pipeline
+     - Print checkpoint details with full context
+     - Wait for user input
+  5. If NOT auto (manual mode):
+     - PAUSE pipeline
+     - Print checkpoint details
+     - Wait for user input
+```
+
+### Resume After Checkpoint
+
+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>~/.claude/qaa/agents/qa-pipeline-orchestrator.md</execution_context>
+    <resume_context>
+    Pipeline state:
+    - Completed stages: {list of completed stages with their results}
+    - Current stage: {stage that triggered checkpoint}
+    - Checkpoint response: {user's response or decision}
+    - Artifacts produced so far: {list of files with paths}
+
+    Resume from: {exact step in pipeline to resume from}
+    User decision: {what user chose at checkpoint}
+    </resume_context>
+  "
+)
+```
+
+### Stale Chain Flag Protection
+
+At orchestrator init, if `--auto` was NOT passed AND `auto_advance` config is false:
+```bash
+node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
+```
+
+At pipeline completion (success or failure):
+```bash
+node bin/qaa-tools.cjs config-set workflow._auto_chain_active false 2>/dev/null || true
+```
+
+</auto_advance>