qaa-agent 1.0.0 → 1.2.0

package/workflows/qa-testid.md

@@ -0,0 +1,356 @@
+<purpose>
+Scan a frontend codebase, audit every interactive UI element for data-testid coverage, and inject missing data-testid attributes following the `{context}-{description}-{element-type}` naming convention from CLAUDE.md. Operates on a separate branch (`qa/testid-{project}-{date}`) to keep the working copy clean. Produces TESTID_AUDIT_REPORT.md with coverage scores, proposed values, and a decision gate. The user reviews and approves proposed changes before injection. Use this workflow to prepare a frontend codebase for reliable Tier 1 test selectors.
+</purpose>
+
+<required_reading>
+- `CLAUDE.md` -- data-testid Convention (naming pattern, context derivation, element-type suffix table, third-party handling), Locator Strategy (Tier 1 includes data-testid)
+- `data-testid-SKILL.md` -- Complete naming convention reference, framework-specific injection syntax, edge case handling
+- `agents/qaa-scanner.md` -- Scanner agent definition (detects frontend framework, enumerates component files)
+- `agents/qaa-testid-injector.md` -- TestID injector agent definition (4-phase: SCAN, AUDIT, INJECT, VALIDATE)
+- `templates/scan-manifest.md` -- SCAN_MANIFEST.md format contract
+- `templates/testid-audit-report.md` -- TESTID_AUDIT_REPORT.md format contract
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for the source directory path.
+
+**Supported arguments:**
+- `<path>` -- Path to the frontend source directory (positional)
+- No arguments -- auto-detect frontend directories
+
+**Parsing logic:**
+
+```bash
+SOURCE_DIR=""
+
+# Parse positional path argument from $ARGUMENTS
+```
+
+**Validation:**
+- If a path is provided, verify it exists and is a directory. If not, print error: `"Error: Source directory does not exist: {path}"` and STOP.
+- If no path provided, proceed to auto-detection in the next step.
+</step>
+
+<step name="detect_frontend">
+## Step 2: Detect Frontend Directory and Framework
+
+If no source directory was specified, auto-detect by searching for common frontend directory patterns.
+
+**Directory detection order:**
+
+1. `src/` -- Most common source directory
+2. `app/` -- Next.js app directory, or generic app directory
+3. `components/` -- Component-focused projects
+4. `pages/` -- File-based routing frameworks (Next.js, Nuxt)
+5. `lib/` -- Library projects
+6. `client/` -- Monorepo client directory
+
+**Detection logic:**
+
+```bash
+if SOURCE_DIR is empty:
+  for dir in src app components pages lib client:
+    if directory exists at "${dir}":
+      SOURCE_DIR="${dir}"
+      break
+```
+
+**If no frontend directory found:**
+
+Print error and STOP:
+```
+Error: No frontend source directory found.
+Searched for: src/, app/, components/, pages/, lib/, client/
+Provide the source directory path as an argument: /qa-testid <path>
+```
+
+**Detect frontend framework:**
+
+Check for framework indicators in the project root:
+
+| Framework | Detection Method |
+|-----------|-----------------|
+| React | `react` or `react-dom` in package.json dependencies; `*.jsx` or `*.tsx` files present |
+| Vue | `vue` in package.json dependencies; `*.vue` files present |
+| Angular | `@angular/core` in package.json dependencies; `*.component.ts` and `*.component.html` files present |
+| Svelte | `svelte` in package.json dependencies; `*.svelte` files present |
+| Plain HTML | None of the above; `*.html` files present (excluding build output) |
+
+```bash
+FRONTEND_FRAMEWORK=""
+
+# Check package.json for framework dependencies
+# Check for framework-specific file extensions in SOURCE_DIR
+```
+
+**If no frontend framework detected:**
+
+Print error and STOP:
+```
+Error: No frontend framework detected.
+Checked package.json dependencies and file extensions in {SOURCE_DIR}.
+No React (.jsx/.tsx), Vue (.vue), Angular (.component.ts), Svelte (.svelte), or HTML files found.
+
+This workflow requires a frontend codebase with UI components to inject data-testid attributes.
+```
+
+**Count component files:**
+
+```bash
+# Count files matching the detected framework's extensions
+COMPONENT_COUNT=$(find "${SOURCE_DIR}" -type f \( -name "*.tsx" -o -name "*.jsx" -o -name "*.vue" -o -name "*.svelte" -o -name "*.component.html" \) \
+  ! -path "*/node_modules/*" ! -path "*/dist/*" ! -path "*/build/*" \
+  ! -name "*.test.*" ! -name "*.spec.*" ! -name "*.stories.*" | wc -l)
+```
+
+If `COMPONENT_COUNT` is 0, print error and STOP:
+```
+Error: No component files found in {SOURCE_DIR}.
+Framework detected: {FRONTEND_FRAMEWORK}
+Expected file patterns: {patterns for that framework}
+```
+
+**Print detection results:**
+
+```
+Frontend Detection:
+  Source Directory: {SOURCE_DIR}
+  Framework: {FRONTEND_FRAMEWORK}
+  Component Files: {COMPONENT_COUNT}
+```
+</step>
+
+<step name="run_scanner">
+## Step 3: Spawn Scanner Agent
+
+Spawn the scanner agent to produce SCAN_MANIFEST.md with the frontend component file list.
+
+```
+Task(
+  prompt="
+    <objective>Scan frontend repository and produce SCAN_MANIFEST.md with component file enumeration</objective>
+    <execution_context>@agents/qaa-scanner.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    </files_to_read>
+    <parameters>
+    dev_repo_path: {project root}
+    qa_repo_path: null
+    output_path: {OUTPUT_DIR}/SCAN_MANIFEST.md
+    </parameters>
+  "
+)
+```
+
+**Set output directory:**
+
+```bash
+OUTPUT_DIR=".qa-output"
+mkdir -p "${OUTPUT_DIR}"
+```
+
+**Handle scanner return:**
+
+- Extract `has_frontend` -- MUST be `true`. If `false`, print error and STOP:
+  ```
+  Error: Scanner reports has_frontend: false.
+  The detected framework ({FRONTEND_FRAMEWORK}) and component files ({COMPONENT_COUNT}) suggest frontend is present,
+  but the scanner could not classify them as frontend components.
+  Check SCAN_MANIFEST.md for details: {OUTPUT_DIR}/SCAN_MANIFEST.md
+  ```
+
+**Verify SCAN_MANIFEST.md exists:**
+
+```bash
+[ -f "${OUTPUT_DIR}/SCAN_MANIFEST.md" ] && echo "FOUND" || echo "MISSING"
+```
+
+If missing, print error and STOP.
+</step>
+
+<step name="run_testid_injector">
+## Step 4: Spawn TestID Injector Agent
+
+Spawn the testid-injector agent which operates in 4 phases: SCAN, AUDIT, INJECT, VALIDATE.
+
+```
+Task(
+  prompt="
+    <objective>Audit frontend components for data-testid coverage and inject missing attributes</objective>
+    <execution_context>@agents/qaa-testid-injector.md</execution_context>
+    <files_to_read>
+    - {OUTPUT_DIR}/SCAN_MANIFEST.md
+    - CLAUDE.md
+    - data-testid-SKILL.md
+    </files_to_read>
+    <parameters>
+    source_dir: {SOURCE_DIR}
+    frontend_framework: {FRONTEND_FRAMEWORK}
+    output_path: {OUTPUT_DIR}/TESTID_AUDIT_REPORT.md
+    </parameters>
+  "
+)
+```
+
+**Injector agent phases:**
+
+1. **SCAN phase:** The injector detects the framework, lists component files, classifies them by interaction density (HIGH/MEDIUM/LOW), and sorts by priority.
+
+2. **AUDIT phase:** For each component file, the injector identifies every interactive element (buttons, inputs, selects, forms, links, modals, etc.), checks for existing data-testid attributes, proposes values for missing attributes following `{context}-{description}-{element-type}` convention, classifies elements by priority (P0/P1/P2), and calculates the coverage score.
+
+3. **CHECKPOINT:** The injector presents the TESTID_AUDIT_REPORT.md to the user for review before injecting. The user can:
+   - Approve all proposed values
+   - Reject specific elements
+   - Rename proposed values
+   - Approve renaming of non-compliant existing values
+   - Change priority classifications
+
+4. **INJECT phase (after approval):** Creates a separate branch `qa/testid-inject-{YYYY-MM-DD}`, injects approved data-testid attributes using framework-specific syntax (JSX attributes for React, HTML attributes for Vue templates, `[attr.data-testid]` binding for Angular), preserves all existing formatting, and preserves existing data-testid values.
+
+5. **VALIDATE phase:** Runs syntax checks on all modified files, verifies uniqueness of data-testid values per page/route scope, checks naming convention compliance, and verifies no unintended source code changes (non-interference check). If syntax fails, reverts the specific file.
+
+**Handle injector return:**
+
+Extract:
+- `report_path` -- Path to TESTID_AUDIT_REPORT.md
+- `changelog_path` -- Path to INJECTION_CHANGELOG.md
+- `branch` -- Name of the injection branch
+- `coverage_before` -- Coverage before injection
+- `coverage_after` -- Coverage after injection
+- `elements_injected` -- Count of injected attributes
+- `elements_deferred` -- Count of deferred elements
+- `files_modified` -- Count of modified files
+- `validation_passed` -- Whether all validation checks passed
+</step>
+
+<step name="create_branch_and_commit">
+## Step 5: Create Branch and Commit
+
+The testid-injector agent handles branch creation and commits internally on the `qa/testid-inject-{YYYY-MM-DD}` branch. Verify the branch was created and commits exist.
+
+**Verify branch:**
+
+```bash
+git branch --list "qa/testid-inject-*"
+```
+
+If the branch does not exist, the injector may not have reached the injection phase (stopped at audit checkpoint). This is expected behavior -- the audit report is still produced.
+
+**Verify commit (if injection was performed):**
+
+```bash
+git log --oneline -3 "qa/testid-inject-*" 2>/dev/null
+```
+</step>
+
+<step name="print_summary">
+## Step 6: Print Summary
+
+Print a comprehensive summary of the testid injection results.
+
+```
+=== TestID Injection Complete ===
+
+Frontend:
+  Framework:        {FRONTEND_FRAMEWORK}
+  Source Directory:  {SOURCE_DIR}
+  Component Files:  {COMPONENT_COUNT}
+
+Coverage:
+  Before: {coverage_before}%
+  After:  {coverage_after}%
+  Change: +{coverage_after - coverage_before}%
+
+Elements:
+  Total Interactive:  {total_elements}
+  Already Had TestID: {existing_count}
+  Injected:           {elements_injected}
+  Deferred (P1/P2):   {elements_deferred}
+
+By Priority:
+  P0 (inputs, buttons, forms): {p0_count} ({p0_injected} injected)
+  P1 (links, alerts, toggles): {p1_count} ({p1_injected} injected)
+  P2 (images, badges, tables):  {p2_count} ({p2_injected} injected)
+
+Validation:
+  Syntax Check:         {PASS|FAIL}
+  Uniqueness Check:     {PASS|FAIL}
+  Convention Check:     {PASS|FAIL}
+  Non-Interference:     {PASS|FAIL}
+
+Branch: {branch_name}
+Files Modified: {files_modified}
+
+Artifacts:
+  - {OUTPUT_DIR}/SCAN_MANIFEST.md
+  - {OUTPUT_DIR}/TESTID_AUDIT_REPORT.md
+  - {OUTPUT_DIR}/INJECTION_CHANGELOG.md  (after injection)
+
+Next Steps:
+  1. Review changes on branch: git diff main..{branch_name}
+  2. If approved, merge: git merge {branch_name}
+  3. Run tests to verify no regressions
+=================================
+```
+
+**If injection was not performed (stopped at audit checkpoint):**
+
+```
+=== TestID Audit Complete (Injection Pending) ===
+
+The audit report has been produced. Review the proposed data-testid values
+in {OUTPUT_DIR}/TESTID_AUDIT_REPORT.md and re-run with approvals to inject.
+
+Coverage Score: {coverage_before}%
+Decision: {SELECTIVE|TARGETED|FULL PASS|P0 FIRST}
+Missing TestIDs: {missing_count} ({p0_missing} P0, {p1_missing} P1, {p2_missing} P2)
+=============================================
+```
+</step>
+
+</process>
+
+<output>
+This workflow audits and injects data-testid attributes into frontend components.
+
+**Artifacts produced:**
+
+| Artifact | When Produced | Description |
+|----------|---------------|-------------|
+| SCAN_MANIFEST.md | Always | Repository scan with component file list and framework detection |
+| TESTID_AUDIT_REPORT.md | Always | Comprehensive audit: coverage score, per-element tables, naming compliance, decision gate |
+| INJECTION_CHANGELOG.md | After injection approval | Per-file log of every injection action with validation results |
+| Modified source files | After injection approval | Component files with data-testid attributes added, on separate branch |
+
+**Branch management:**
+- Injection branch: `qa/testid-inject-{YYYY-MM-DD}`
+- Working copy on the original branch is NOT modified
+- User merges the injection branch if approved
+
+**Decision gate thresholds (from CLAUDE.md):**
+
+| Current Coverage | Decision | Strategy |
+|-----------------|----------|----------|
+| > 90% | SELECTIVE | Inject only P0 missing elements |
+| 50% - 90% | TARGETED | Inject P0 and P1 missing elements |
+| 1% - 49% | FULL PASS | Inject all P0, P1, P2 elements |
+| 0% | P0 FIRST | Inject P0 elements only, then re-audit |
+</output>
+
+<error_handling>
+| Error | Cause | Action |
+|-------|-------|--------|
+| Source directory does not exist | Invalid path argument | Print error with path, STOP |
+| No frontend directory found | No common frontend dirs in project | Print error listing searched dirs, suggest providing path, STOP |
+| No frontend framework detected | Missing framework deps and file extensions | Print error with detection details, STOP |
+| No component files found | Directory exists but no components | Print error with expected patterns for the detected framework, STOP |
+| Scanner reports has_frontend: false | Scanner classification issue | Print error with suggestion to check SCAN_MANIFEST.md, STOP |
+| SCAN_MANIFEST.md missing | Scanner failed | Print error, STOP |
+| Syntax check fails after injection | Injection broke file syntax | Injector reverts the specific file automatically, reports in changelog |
+| Duplicate data-testid detected | Same value on same rendered page | Injector renames the newer injection to disambiguate |
+| Non-compliant existing values | Existing data-testid does not follow convention | Reported in audit but NOT auto-renamed (user decides) |
+</error_handling>

package/workflows/qa-validate.md

@@ -0,0 +1,295 @@
+<purpose>
+Validate existing test files against CLAUDE.md QA standards using a 4-layer check (Syntax, Structure, Dependencies, Logic). Runs a fix loop (validate, fix, re-validate) up to 3 times. If failures remain after the fix loop, optionally spawns the bug-detective agent to classify failures. Produces VALIDATION_REPORT.md and optionally FAILURE_CLASSIFICATION_REPORT.md. Use this workflow to audit test quality in any test suite -- whether generated by the QA pipeline or hand-written.
+</purpose>
+
+<required_reading>
+- `CLAUDE.md` -- QA automation standards, quality gates, locator strategy, POM rules, assertion specificity rules
+- `agents/qaa-validator.md` -- Validator agent definition (4-layer validation, fix loop, confidence assessment)
+- `agents/qaa-bug-detective.md` -- Bug detective agent definition (failure classification, auto-fix for test errors)
+- `templates/validation-report.md` -- VALIDATION_REPORT.md format contract
+- `templates/failure-classification.md` -- FAILURE_CLASSIFICATION_REPORT.md format contract
+</required_reading>
+
+<process>
+
+<step name="parse_arguments">
+## Step 1: Parse Arguments
+
+Parse `$ARGUMENTS` for the test directory path and optional flags.
+
+**Supported arguments:**
+- `<path>` -- Path to the test directory to validate (positional)
+- `--classify` -- If set, spawn bug-detective after validation to classify remaining failures
+- No arguments -- auto-detect test directories
+
+**Parsing logic:**
+
+```bash
+TEST_DIR=""
+CLASSIFY_FAILURES=false
+
+# Parse positional path argument
+# Parse --classify flag
+```
+
+**Validation:**
+- If a path is provided, verify it exists and is a directory. If not, print error: `"Error: Test directory does not exist: {path}"` and STOP.
+- If no path provided, proceed to auto-detection in the next step.
+</step>
+
+<step name="detect_test_directories">
+## Step 2: Detect Test Directories
+
+If no test directory was specified, auto-detect by searching for common test directory patterns.
+
+**Detection order (check each, use the first match):**
+
+1. `tests/` -- Standard test directory
+2. `__tests__/` -- Jest convention
+3. `cypress/` -- Cypress test directory
+4. `e2e/` -- E2E test directory
+5. `test/` -- Alternative singular form
+6. `spec/` -- RSpec/generic spec directory
+
+**Detection logic:**
+
+```bash
+if TEST_DIR is empty:
+  for dir in tests __tests__ cypress e2e test spec:
+    if directory exists at "${dir}":
+      TEST_DIR="${dir}"
+      break
+```
+
+**If no test directory found:**
+
+Print error and STOP:
+```
+Error: No test directory found.
+Searched for: tests/, __tests__/, cypress/, e2e/, test/, spec/
+Provide the test directory path as an argument: /qa-validate <path>
+```
+
+**Count test files:**
+
+```bash
+TEST_FILE_COUNT=$(find "${TEST_DIR}" -type f \( -name "*.test.*" -o -name "*.spec.*" -o -name "*.cy.*" -o -name "*.e2e.*" \) | wc -l)
+```
+
+If `TEST_FILE_COUNT` is 0, print error: `"Error: No test files found in {TEST_DIR}. Expected files matching *.test.*, *.spec.*, *.cy.*, or *.e2e.*"` and STOP.
+
+**Print detection results:**
+
+```
+Test directory: {TEST_DIR}
+Test files found: {TEST_FILE_COUNT}
+```
+</step>
+
+<step name="build_file_list">
+## Step 3: Build File List for Validation
+
+Enumerate all test files and supporting files (page objects, fixtures) to validate.
+
+**File discovery:**
+
+Glob for test-related files in the detected directory:
+- Test specs: `**/*.test.*`, `**/*.spec.*`, `**/*.cy.*`, `**/*.e2e.*`
+- Page objects: `**/pages/**/*`, `**/page-objects/**/*`, `**/support/page-objects/**/*`
+- Fixtures: `**/fixtures/**/*`
+- Config files: test framework configs at the project root
+
+**Build a generation-plan-equivalent file list:**
+
+The validator agent expects a file list (normally from the generation plan). For this workflow, construct a synthetic file list from the discovered files:
+
+```markdown
+## Files to Validate
+
+| File Path | Type |
+|-----------|------|
+| tests/unit/auth.unit.spec.ts | test_spec |
+| tests/api/users.api.spec.ts | test_spec |
+| pages/auth/LoginPage.ts | page_object |
+| fixtures/auth-data.ts | fixture |
+| ... | ... |
+```
+
+**Set output directory:**
+
+```bash
+OUTPUT_DIR=".qa-output"
+mkdir -p "${OUTPUT_DIR}"
+```
+</step>
+
+<step name="run_validator">
+## Step 4: Spawn Validator Agent
+
+Spawn the validator agent to perform 4-layer validation with fix loop.
+
+```
+Task(
+  prompt="
+    <objective>Validate test files against CLAUDE.md standards across 4 layers (Syntax, Structure, Dependencies, Logic)</objective>
+    <execution_context>@agents/qaa-validator.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - {synthetic file list or generation plan path}
+    </files_to_read>
+    <parameters>
+    test_dir: {TEST_DIR}
+    output_path: {OUTPUT_DIR}/VALIDATION_REPORT.md
+    file_list: {list of test file paths}
+    mode: validation
+    </parameters>
+  "
+)
+```
+
+**Handle validator return:**
+
+Extract from the validator's return values:
+- `overall_status` -- PASS, PASS_WITH_WARNINGS, or FAIL
+- `confidence` -- HIGH, MEDIUM, or LOW
+- `layers_summary` -- per-layer PASS/FAIL status
+- `fix_loops_used` -- number of fix iterations (1-3)
+- `issues_found` -- total issues discovered
+- `issues_fixed` -- issues auto-fixed (HIGH confidence only)
+- `unresolved_count` -- issues remaining after fix loops
+
+**Verify VALIDATION_REPORT.md exists:**
+
+```bash
+[ -f "${OUTPUT_DIR}/VALIDATION_REPORT.md" ] && echo "FOUND" || echo "MISSING"
+```
+
+If missing, print error: `"Error: Validator did not produce VALIDATION_REPORT.md."` and STOP.
+</step>
+
+<step name="classify_failures">
+## Step 5: Optionally Spawn Bug Detective
+
+If the `--classify` flag was set AND the validator reported failures (unresolved_count > 0), spawn the bug-detective agent to classify the remaining failures.
+
+**Gate check:**
+
+```
+if CLASSIFY_FAILURES is false:
+  Skip this step -- print note: "Skipping failure classification. Use --classify flag to enable."
+
+if unresolved_count is 0:
+  Skip this step -- print note: "No unresolved failures to classify."
+```
+
+**Spawn bug-detective agent:**
+
+```
+Task(
+  prompt="
+    <objective>Run test suite and classify failures into APPLICATION BUG, TEST CODE ERROR, ENVIRONMENT ISSUE, or INCONCLUSIVE</objective>
+    <execution_context>@agents/qaa-bug-detective.md</execution_context>
+    <files_to_read>
+    - CLAUDE.md
+    - {test file paths with failures}
+    </files_to_read>
+    <parameters>
+    test_dir: {TEST_DIR}
+    output_path: {OUTPUT_DIR}/FAILURE_CLASSIFICATION_REPORT.md
+    </parameters>
+  "
+)
+```
+
+**Handle detective return:**
+
+Extract from the detective's return values:
+- `total_failures` -- number of failures analyzed
+- `classification_breakdown` -- counts per category (app_bug, test_error, env_issue, inconclusive)
+- `auto_fixes_applied` -- count of TEST CODE ERROR fixes at HIGH confidence
+- `auto_fixes_verified` -- count of fixes that passed re-verification
+
+**Verify FAILURE_CLASSIFICATION_REPORT.md exists (if detective was spawned):**
+
+```bash
+[ -f "${OUTPUT_DIR}/FAILURE_CLASSIFICATION_REPORT.md" ] && echo "FOUND" || echo "MISSING"
+```
+</step>
+
+<step name="print_summary">
+## Step 6: Print Validation Summary
+
+Print a human-readable summary of the validation results.
+
+```
+=== Validation Complete ===
+
+Test Directory: {TEST_DIR}
+Files Validated: {file_count}
+Fix Loops Used: {fix_loops_used} of 3
+
+Layer Results:
+  Syntax:       {PASS|FAIL}
+  Structure:    {PASS|FAIL}
+  Dependencies: {PASS|FAIL}
+  Logic:        {PASS|FAIL}
+
+Issues:
+  Found:      {issues_found}
+  Auto-fixed: {issues_fixed}
+  Unresolved: {unresolved_count}
+
+Overall Status: {PASS|PASS_WITH_WARNINGS|FAIL}
+Confidence: {HIGH|MEDIUM|LOW}
+
+Artifacts Produced:
+  - {OUTPUT_DIR}/VALIDATION_REPORT.md
+  - {OUTPUT_DIR}/FAILURE_CLASSIFICATION_REPORT.md  (if --classify used)
+```
+
+**If bug detective ran, add classification summary:**
+
+```
+Failure Classification:
+  APPLICATION BUG:    {app_bug_count}
+  TEST CODE ERROR:    {test_error_count}
+  ENVIRONMENT ISSUE:  {env_issue_count}
+  INCONCLUSIVE:       {inconclusive_count}
+  Auto-fixed:         {auto_fixes_applied}
+```
+
+```
+===========================
+```
+</step>
+
+</process>
+
+<output>
+This workflow validates existing test files and produces quality reports.
+
+**Artifacts produced:**
+
+| Artifact | When Produced | Description |
+|----------|---------------|-------------|
+| VALIDATION_REPORT.md | Always | 4-layer validation results (Syntax, Structure, Dependencies, Logic) with fix loop history and confidence level |
+| FAILURE_CLASSIFICATION_REPORT.md | When --classify flag set AND failures exist | Per-failure classification (APPLICATION BUG, TEST CODE ERROR, ENVIRONMENT ISSUE, INCONCLUSIVE) with evidence and auto-fix log |
+
+**Side effects:**
+- Test files may be modified in-place by HIGH-confidence auto-fixes from the validator
+- Test files may be modified by HIGH-confidence TEST CODE ERROR fixes from the bug detective
+- No git branches created (fixes applied to working tree)
+- No PRs created
+</output>
+
+<error_handling>
+| Error | Cause | Action |
+|-------|-------|--------|
+| Test directory does not exist | Invalid path argument | Print error with path, STOP |
+| No test directory found | No common test dirs in project | Print error listing searched dirs, suggest providing path, STOP |
+| No test files found in directory | Directory exists but contains no test files | Print error with expected patterns, STOP |
+| VALIDATION_REPORT.md missing | Validator failed silently | Print error, STOP |
+| Fix loop exhausted (3 loops) | Issues cannot be auto-resolved | Validator checkpoints with unresolved issue details |
+| Test runner not detected | No test framework config found | Bug detective checkpoints for user to specify runner |
+| Test runner fails to start | Missing dependencies or broken config | Bug detective classifies as ENVIRONMENT ISSUE |
+</error_handling>