qaa-agent 1.6.2 → 1.7.0

package/workflows/qa-start.md

@@ -1,1168 +1,1192 @@
-<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="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
-    </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
-    </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
-    </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
-    </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
-
-**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</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
-    </files_to_read>
-    <parameters>
-    output_path: {output_dir}/FAILURE_CLASSIFICATION_REPORT.md
-    </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>
+<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="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
+    </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
+    </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
+    </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
+    </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
+    </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>