npm - qaa-agent - Versions diffs - 1.9.0 → 1.9.2 - Mend

qaa-agent 1.9.0 → 1.9.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (12) hide show

package/CHANGELOG.md +180 -177
package/CLAUDE.md +557 -557
package/README.md +1 -1
package/VERSION +1 -0
package/agents/qa-pipeline-orchestrator.md +1424 -1424
package/agents/qaa-bug-detective.md +654 -630
package/agents/qaa-e2e-runner.md +576 -552
package/agents/qaa-executor.md +829 -805
package/agents/qaa-project-researcher.md +400 -339
package/commands/qa-test-report.md +219 -0
package/package.json +3 -2
package/workflows/qa-start.md +1405 -1262

package/workflows/qa-start.md CHANGED Viewed

@@ -1,1262 +1,1405 @@
-<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="research">
-## Step 3b: 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 1b: 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 Context7 MCP as the primary source for all framework and library questions. Produce research documents consumed by downstream agents.</objective>
-    <execution_context>@agents/qaa-project-researcher.md</execution_context>
-    <files_to_read>
-    - CLAUDE.md
-    - ~/.claude/qaa/MY_PREFERENCES.md (if exists)
-    - ${output_dir}/SCAN_MANIFEST.md
-    </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)
-    </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
-    - {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)
-    </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)
-    </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>
+<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>