qaa-agent 1.6.2 → 1.7.0

package/workflows/qa-testid.md

@@ -1,356 +1,384 @@
-<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>
+<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. Use Playwright MCP to verify against live DOM. Use codebase map for component structure context. Update locator registry with discovered and injected locators.</objective>
+    <execution_context>@agents/qaa-testid-injector.md</execution_context>
+    <files_to_read>
+    - {OUTPUT_DIR}/SCAN_MANIFEST.md
+    - CLAUDE.md
+    - data-testid-SKILL.md
+    - .qa-output/locators/LOCATOR_REGISTRY.md (if exists -- existing locators to cross-reference)
+    - .qa-output/codebase/CODE_PATTERNS.md (if exists -- component naming conventions for context derivation)
+    - .qa-output/codebase/TEST_SURFACE.md (if exists -- UI component list with props/events)
+    - .qa-output/codebase/TESTABILITY.md (if exists -- component testability for injection priority)
+    </files_to_read>
+    <parameters>
+    source_dir: {SOURCE_DIR}
+    frontend_framework: {FRONTEND_FRAMEWORK}
+    output_path: {OUTPUT_DIR}/TESTID_AUDIT_REPORT.md
+    app_url: {auto-detect from dev server or ask user}
+    </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.
+
+6. **BROWSER VERIFY phase (if app URL available and Playwright MCP connected):**
+
+   After injection and static validation, use Playwright MCP to verify the injected `data-testid` attributes are present in the rendered DOM:
+
+   1. Navigate to each page/route that has injected components:
+      ```
+      mcp__playwright__browser_navigate({ url: "{app_url}/{route}" })
+      ```
+
+   2. Take an accessibility snapshot to inspect the rendered DOM:
+      ```
+      mcp__playwright__browser_snapshot()
+      ```
+
+   3. Cross-reference: for each injected `data-testid`, verify it appears in the snapshot. Report:
+      - **CONFIRMED**: `data-testid` found in rendered DOM
+      - **NOT RENDERED**: Component exists in source but not rendered on this route (may appear conditionally)
+      - **MISSING**: `data-testid` expected but not found in DOM (possible injection error)
+
+   4. Add browser verification results to the TESTID_AUDIT_REPORT.md as a "Browser Verification" section.
+
+   This step is **optional** -- if no app URL is available or the app is not running, skip and rely on static validation only.
+
+**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>