@keber/qa-framework 1.10.0 → 1.12.0

package/docs/usage-with-agent.md

@@ -1,12 +1,14 @@
 # docs/usage-with-agent.md
 
-## Using `qa-framework` with an IDE Agent (GitHub Copilot)
+## Using `qa-framework` with an IDE Agent (GitHub Copilot or Claude Code)
 
 ---
 
 ## Overview
 
-This framework is designed so that an IDE agent (such as GitHub Copilot in VS Code) can:
+`init` and `upgrade` always generate artifacts for both GitHub Copilot and Claude Code
+in parallel - there is no agent detection. This framework is designed so that either
+IDE agent can:
 
 1. Understand the QA structure by reading the agent instruction files
 2. Navigate the `qa/` directory predictably
@@ -42,11 +44,11 @@ This framework is designed so that an IDE agent (such as GitHub Copilot in VS Co
 
 ---
 
-## Setting Up Agent Instructions in VS Code
+## Setting Up Agent Instructions in VS Code (GitHub Copilot)
 
-### Option A — Workspace instructions file (recommended)
+### Option A - Workspace instructions file (recommended)
 
-`init` generates `.github/copilot-instructions.md` automatically. It contains the full
+`init` generates `.github/instructions/qa-framework.instructions.md` automatically. It contains the full
 pipeline sequencer with 11 agent behavior rules, the QA pipeline table, and ADO detection.
 No manual setup needed.
 
@@ -56,7 +58,7 @@ To regenerate after an upgrade:
 npx qa-framework upgrade
 ```
 
-### Option B — Reference skills directly in the agent conversation
+### Option B - Reference skills directly in the agent conversation
 
 Paste a skill path into the Copilot chat:
 
@@ -64,7 +66,7 @@ Paste a skill path into the Copilot chat:
 Read .github/skills/qa-module-analysis/SKILL.md and analyze the module at {URL}
 ```
 
-### Option C — Individual task prompts
+### Option C - Individual task prompts
 
 For each major QA task, ask the agent to load the relevant skill:
 
@@ -75,6 +77,77 @@ tests for the submodule {name}
 
 ---
 
+## Setting Up Agent Instructions in Claude Code
+
+`init` and `upgrade` generate two Claude-Code-native artifacts automatically, no manual
+setup needed:
+
+- `.claude/rules/qa-framework.md` - the Claude Code equivalent of the Copilot
+  `.instructions.md` file. It has no frontmatter, which means it loads unconditionally in
+  every session (the same effect as `applyTo: '**'`). It contains the same 11 agent
+  behavior rules and pipeline table as the Copilot instructions, with every skill
+  reference expressed as a `/qa-{name}` slash command instead of "load this file".
+- `.claude/commands/qa-{name}.md` - one thin wrapper per skill, generated dynamically
+  from whatever folders exist under `.github/skills/` at install/upgrade time. Each
+  wrapper is a single instruction: `Read the full skill at .github/skills/qa-{name}/SKILL.md
+  FIRST, then follow its instructions exactly`, plus the stage prerequisite. There is zero
+  duplication of skill content and therefore zero drift - if a skill is updated, every
+  command that points to it picks up the change with no regeneration needed.
+
+### Using a command
+
+In a Claude Code session, invoke the pipeline stage directly:
+
+```
+/qa-module-analysis
+```
+
+Claude reads `.github/skills/qa-module-analysis/SKILL.md` and follows it exactly, the
+same way the Copilot pipeline table routes to that file.
+
+### Regenerating after an upgrade
+
+```bash
+npx qa-framework upgrade
+```
+
+This refreshes both `.claude/commands/qa-*.md` and `.claude/rules/qa-framework.md` the
+same safe way it refreshes the Copilot artifacts (framework-owned, always overwritten
+with the current version; nothing else under `.claude/` is touched).
+
+---
+
+## Optional: ANALISIS/PLAN Mode (Claude Code only, ADO-gated)
+
+Some teams run a sprint-centric manual testing workflow in parallel with the 6-stage
+pipeline: an analysis document, a test plan trace-linked to Azure DevOps work items,
+ad-hoc QA advisory chat, and a sprint closing results report. This mode is:
+
+- **Optional** - off by default.
+- **Gated** by `integrations.azureDevOps.sprintCycle.enabled` in
+  `qa/qa-framework.config.json` (it requires Azure DevOps enabled, since three of the
+  four agents depend on ADO work items or an ADO-generated execution report).
+- **Claude Code only, by design, not by omission.** Each agent is a Claude Code subagent
+  with its own `tools`/`model` frontmatter (e.g. `qa-asesoria` intentionally has no
+  `Write`/`Bash`). GitHub Copilot has no equivalent primitive, so no `.github/` artifact
+  is generated for this mode.
+
+When enabled, `init`/`upgrade` generate four subagents under `.claude/agents/`:
+
+| Agent | Purpose |
+|---|---|
+| `qa-analisis.md` | Analysis document: test universe, automation feasibility, P0-P3 prioritization, excluded universe, traceability matrix |
+| `qa-plan.md` | Default mode: executive summary + a trace-linked test case table, executable within the configured manual-testing timebox |
+| `qa-asesoria.md` | Chat-only QA advisory (no `Write`/`Bash`) - answers point questions, redirects to `qa-plan`/`qa-analisis` when a full document is actually needed |
+| `qa-informe-resultados.md` | Narrative sprint closing report built from an execution report already produced by the `qa-ado-integration` skill; updates incrementally, never overwrites prior sections |
+
+Sprint duration, manual-testing timebox, date format, and timezone are parameterized
+from `integrations.azureDevOps.sprintCycle` (with neutral defaults - 8-day sprint,
+2-day timebox, `dd-mm-aaaa`, `America/Santiago` - when a field is omitted). See
+[docs/installation.md](installation.md) for the config shape.
+
+---
+
 ## Typical Agent Session Workflow
 
 ### Session 1: Initial Module Analysis
@@ -124,7 +197,7 @@ tests for the submodule {name}
 
 ### DO
 
-- Read `qa/AGENT-NEXT-STEPS.md` at the start of each conversation (auto-enforced by copilot-instructions.md)
+- Read `qa/AGENT-NEXT-STEPS.md` at the start of each conversation (auto-enforced by `.github/instructions/qa-framework.instructions.md` for Copilot, or `.claude/rules/qa-framework.md` for Claude Code)
 - Load the relevant skill from `.github/skills/` before starting any QA task
 - Save all artifacts in the exact path specified by `qa/QA-STRUCTURE-GUIDE.md`
 - Use TC-ID, RN-ID, FL-ID naming consistently
@@ -181,7 +254,8 @@ This performs:
 ## Continuing from a Previous Session
 
 The agent reads `qa/AGENT-NEXT-STEPS.md` automatically at the start of every conversation
-(enforced by `.github/copilot-instructions.md` rule 0). For additional context:
+(enforced by rule 0 in `.github/instructions/qa-framework.instructions.md` for Copilot,
+or `.claude/rules/qa-framework.md` for Claude Code). For additional context:
 
 ```
 "Read qa/README.md and qa/memory/INDEX.md, then tell me where we left off."

package/examples/module-example/suppliers/00-inventory.md

@@ -1,4 +1,4 @@
-# Suppliers — Inventory
+# Suppliers - Inventory
 
 **Module**: Suppliers (SUP)
 **Submodule**: Create / Edit / List

package/examples/module-example/suppliers/suppliers-create.spec.ts

@@ -15,16 +15,16 @@
 
 import { test, expect } from '@playwright/test';
 
-// EXEC_IDX: unique per minute-window — prevents data collisions between runs
+// EXEC_IDX: unique per minute-window - prevents data collisions between runs
 const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
 
 test.describe('Suppliers > Create @P0', () => {
 
   /**
-   * [TC-SUP-CR-001] Create supplier — happy path @P0
+   * [TC-SUP-CR-001] Create supplier - happy path @P0
    * Verifies the complete create flow for a valid supplier.
    */
-  test('[TC-SUP-CR-001] Create supplier — happy path @P0', async ({ page }) => {
+  test('[TC-SUP-CR-001] Create supplier - happy path @P0', async ({ page }) => {
     const supplierName = `QA-Supplier-${EXEC_IDX}`;
     const supplierRut  = `${EXEC_IDX}-K`;
     const supplierEmail = `qa-supplier-${EXEC_IDX}@example.com`;
@@ -57,10 +57,10 @@ test.describe('Suppliers > Create @P0', () => {
   });
 
   /**
-   * [TC-SUP-CR-002] Create supplier — required fields validation @P0
+   * [TC-SUP-CR-002] Create supplier - required fields validation @P0
    * Verifies that the form prevents submission when required fields are empty.
    */
-  test('[TC-SUP-CR-002] Create supplier — required fields validation @P0', async ({ page }) => {
+  test('[TC-SUP-CR-002] Create supplier - required fields validation @P0', async ({ page }) => {
     await page.goto('/suppliers');
     await page.locator('button:has-text("New Supplier")').click();
     await expect(page.locator('.supplier-modal')).toBeVisible();
@@ -79,12 +79,12 @@ test.describe('Suppliers > Create @P0', () => {
   });
 
   /**
-   * [TC-SUP-CR-003] Create supplier — duplicate RUT rejected @P0
+   * [TC-SUP-CR-003] Create supplier - duplicate RUT rejected @P0
    *
-   * NOTE: test.skip active — DEF-001: Duplicate RUT check not enforced server-side.
+   * NOTE: test.skip active - DEF-001: Duplicate RUT check not enforced server-side.
    *       Reactivate when ADO #99001 is resolved.
    */
-  test('[TC-SUP-CR-003] Create supplier — duplicate RUT rejected @P0', async ({ page }) => {
+  test('[TC-SUP-CR-003] Create supplier - duplicate RUT rejected @P0', async ({ page }) => {
     test.skip(true,
       'DEF-001: Duplicate RUT validation not enforced. Reactivate when ADO #99001 is resolved.'
     );

package/integrations/ado-powershell/README.md

@@ -1,4 +1,4 @@
-# Integration — ADO PowerShell Scripts
+# Integration - ADO PowerShell Scripts
 
 PowerShell scripts for Azure DevOps Test Plan management.
 All scripts are parameterized and project-agnostic.

package/integrations/ado-powershell/pipelines/azure-pipeline-qa.yml

@@ -1,5 +1,5 @@
 # -----------------------------------------------------------------------
-# keber/qa-framework — Azure Pipeline QA Template
+# keber/qa-framework - Azure Pipeline QA Template
 # -----------------------------------------------------------------------
 # Parameterized CI pipeline for running Playwright E2E and API tests and
 # syncing results to Azure DevOps Test Plans via SYSTEM_ACCESSTOKEN.
@@ -8,28 +8,28 @@
 # Update 'resources.repositories.name' to match your org/project/repo.
 #
 # Required Pipeline Library Variable Group: "QA-Variables"
-# Create this group in ADO → Pipelines → Library and add the following:
+# Create this group in ADO -> Pipelines -> Library and add the following:
 #
-#   QA_BASE_URL          — Target application URL  (e.g. https://app-qa.example.com)
-#   QA_USER_EMAIL        — Test user email / RUT
-#   QA_USER_PASSWORD     — Test user password                        [secret]
-#   ADO_ORG              — ADO organization slug  (e.g. garcesfruit-desarrollo)
-#   ADO_PROJECT          — ADO project name        (e.g. gf-portalproveedores)
-#   ADO_E2E_PLAN_ID      — Test Plan ID for the E2E suite            (e.g. 27044)
-#   ADO_API_PLAN_ID      — Test Plan ID for the API/integration suite (e.g. 27046)
+#   QA_BASE_URL          - Target application URL  (e.g. https://app-qa.example.com)
+#   QA_USER_EMAIL        - Test user email / RUT
+#   QA_USER_PASSWORD     - Test user password                        [secret]
+#   ADO_ORG              - ADO organization slug  (e.g. my-org)
+#   ADO_PROJECT          - ADO project name        (e.g. my-project)
+#   ADO_E2E_PLAN_ID      - Test Plan ID for the E2E suite
+#   ADO_API_PLAN_ID      - Test Plan ID for the API/integration suite
 #
-#   NOTE on multiple Plan IDs: ADO variable groups store plain strings — there
+#   NOTE on multiple Plan IDs: ADO variable groups store plain strings - there
 #   is no array type. Use one variable per suite (ADO_E2E_PLAN_ID / ADO_API_PLAN_ID).
 #   If the project has only one suite, a single ADO_PLAN_ID variable is enough.
 #   Results are reported to ADO via System.AccessToken (OAuth); no PAT required.
 # -----------------------------------------------------------------------
 
-# Cross-project repository — update <ADO_SOURCE_PROJECT>/<REPO_NAME> as needed
+# Cross-project repository - update <ADO_SOURCE_PROJECT>/<REPO_NAME> as needed
 resources:
   repositories:
     - repository: source
       type: git
-      name: <ADO_SOURCE_PROJECT>/<REPO_NAME>   # e.g. gf-gestion-qa/gf-portalproveedores
+      name: <ADO_SOURCE_PROJECT>/<REPO_NAME>   # e.g. my-qa-project/my-repo
       ref: refs/heads/main
 
 # Trigger: push and PR to main.
@@ -44,15 +44,34 @@ pr:
     include:
       - main
 
-# Optional scheduled run — uncomment and adjust if a nightly regression is needed:
+# Optional scheduled run - uncomment and adjust if a nightly regression is needed:
 # schedules:
-#   - cron: '0 6 * * 1-5'   # 06:00 UTC Mon–Fri (03:00 CLT / 02:00 CLST)
+#   - cron: '0 6 * * 1-5'   # 06:00 UTC Mon-Fri (03:00 CLT / 02:00 CLST)
 #     displayName: Nightly regression
 #     branches:
 #       include:
 #         - main
 #     always: true
 
+# -----------------------------------------------------------------------
+# Pipeline parameters
+# -----------------------------------------------------------------------
+# suiteFilter controls which tests run when the pipeline is triggered manually
+# or from a PR. Scheduled runs always override this to 'all' automatically
+# (see the "Resolve suite filter" step in each test job).
+#
+# Default is 'all' so a plain manual run executes the full suite.
+# Override at queue time to run a subset (e.g. 'smoke', '[P0]', 'login').
+#
+# The value is passed to Playwright via --grep. Special regex characters such
+# as '[' and ']' are escaped by the bash array pattern in the run step, so
+# values like '[P0]' are safe.
+parameters:
+  - name: suiteFilter
+    displayName: 'Test suite filter (grep pattern, or "all" to skip filtering)'
+    type: string
+    default: 'all'
+
 pool:
   vmImage: 'ubuntu-latest'
 
@@ -111,6 +130,21 @@ stages:
   # -----------------------------------------------------------------------
   # Stage 2: E2E Tests (Playwright/Chromium)
   # -----------------------------------------------------------------------
+  # Single-job configuration. For parallel execution with two test users,
+  # split this into two jobs and set QA_AUTH_USER per job:
+  #
+  #   - job: E2E_User1
+  #     variables:
+  #       QA_AUTH_USER: '1'
+  #     ...
+  #   - job: E2E_User2
+  #     variables:
+  #       QA_AUTH_USER: '2'
+  #     ...
+  #
+  # Each job must use a distinct Playwright project (--project=chromium-user1 /
+  # --project=chromium-user2) to avoid session conflicts between parallel users.
+  # -----------------------------------------------------------------------
   - stage: E2E
     displayName: 'E2E Tests (Playwright/Chromium)'
     dependsOn: Setup
@@ -138,11 +172,11 @@ stages:
               HTTP_CODE=$(curl -o /dev/null -s -w "%{http_code}" --max-time 30 "$(QA_BASE_URL)")
               echo "HTTP response: $HTTP_CODE"
               if [ "$HTTP_CODE" -lt 200 ] || [ "$HTTP_CODE" -ge 400 ]; then
-                echo "##[error]Smoke test failed — $(QA_BASE_URL) returned HTTP $HTTP_CODE"
+                echo "##[error]Smoke test failed - $(QA_BASE_URL) returned HTTP $HTTP_CODE"
                 exit 1
               fi
               echo "Smoke test passed (HTTP $HTTP_CODE)"
-            displayName: 'Smoke test — verify QA_BASE_URL is reachable'
+            displayName: 'Smoke test - verify QA_BASE_URL is reachable'
 
           # ---------------------------------------------------------------
           # Playwright Workspaces (Azure App Testing)
@@ -159,9 +193,28 @@ stages:
           #     inlineScript: echo "Authenticated via Entra ID"
 
           - script: |
+              # Scheduled runs always execute the full suite, regardless of the
+              # suiteFilter parameter. This prevents accidental partial runs in
+              # nightly regressions when the parameter was changed by a prior
+              # manual queue.
+              SUITE_FILTER="${{ parameters.suiteFilter }}"
+              if [ "$(Build.Reason)" = "Schedule" ]; then
+                SUITE_FILTER="all"
+                echo "Scheduled run detected - overriding suiteFilter to 'all'"
+              fi
+              echo "Effective suiteFilter: $SUITE_FILTER"
+
+              # Build --grep args as a bash array to safely handle patterns that
+              # contain special regex characters such as '[' and ']'. Inline
+              # string interpolation would break those patterns at the shell level.
+              GREP_ARGS=()
+              if [ "$SUITE_FILTER" != "all" ]; then
+                GREP_ARGS=(--grep "$SUITE_FILTER")
+              fi
+
               cd $(E2E_DIR)
               npx playwright test --project=chromium --ignore-snapshots \
-                --grep-invert "_inspect|_diag"
+                --grep-invert "_inspect|_diag" "${GREP_ARGS[@]}"
             displayName: 'Run E2E tests'
             continueOnError: true
             env:
@@ -173,31 +226,40 @@ stages:
               ADO_PLAN_ID:        $(ADO_E2E_PLAN_ID)
               SYSTEM_ACCESSTOKEN: $(System.AccessToken)
               CI:                 'true'
-              # PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)  # Playwright Workspaces endpoint — enable together with the login task
+              # QA_AUTH_USER: '1'  # Set explicitly when running parallel jobs (user-1 / user-2 model)
+              # PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)  # Playwright Workspaces endpoint - enable together with the login task
 
+          # publishRunAttachments is false because screenshots and traces are
+          # already uploaded as pipeline artifacts below. Setting it to true
+          # would double-publish the same files.
           - task: PublishTestResults@2
             condition: always()
             inputs:
               testResultsFormat:     'JUnit'
-              testResultsFiles:      '**/test-results/**/*.xml'
+              testResultsFiles:      'test-results/junit-results.xml'
               searchFolder:          $(E2E_DIR)
               mergeTestResults:      true
+              publishRunAttachments: false
               failTaskOnFailedTests: true
               testRunTitle:          '[Auto E2E] $(Build.BuildNumber)'
             displayName: 'Publish E2E test results (JUnit)'
 
+          # Artifact names include $(System.JobAttempt) to avoid name collisions
+          # when the job is retried. ADO rejects duplicate artifact names within
+          # the same pipeline run, so without the suffix a retry always fails at
+          # the publish step.
           - task: PublishPipelineArtifact@1
             condition: always()
             inputs:
               targetPath: '$(E2E_DIR)/playwright-report'
-              artifact:   'e2e-playwright-report'
+              artifact:   'e2e-playwright-report-attempt-$(System.JobAttempt)'
             displayName: 'Publish E2E HTML report'
 
           - task: PublishPipelineArtifact@1
             condition: always()
             inputs:
               targetPath: '$(E2E_DIR)/test-results'
-              artifact:   'e2e-test-results'
+              artifact:   'e2e-test-results-attempt-$(System.JobAttempt)'
             displayName: 'Publish E2E trace artifacts'
 
   # -----------------------------------------------------------------------
@@ -237,6 +299,7 @@ stages:
           #     inlineScript: echo "Authenticated via Entra ID"
 
           - script: |
+              # API integration tests do not use suite tags - always run all.
               cd $(API_DIR)
               npx playwright test --grep-invert "_inspect|_diag"
             displayName: 'Run API integration tests'
@@ -250,29 +313,33 @@ stages:
               ADO_PLAN_ID:        $(ADO_API_PLAN_ID)
               SYSTEM_ACCESSTOKEN: $(System.AccessToken)
               CI:                 'true'
-              # PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)  # Playwright Workspaces endpoint — enable together with the login task
+              # PLAYWRIGHT_SERVICE_URL: $(PLAYWRIGHT_SERVICE_URL)  # Playwright Workspaces endpoint - enable together with the login task
 
+          # publishRunAttachments is false because trace artifacts are already
+          # uploaded as pipeline artifacts below.
           - task: PublishTestResults@2
             condition: always()
             inputs:
               testResultsFormat:     'JUnit'
-              testResultsFiles:      '**/test-results/**/*.xml'
+              testResultsFiles:      'test-results/junit-results.xml'
               searchFolder:          $(API_DIR)
               mergeTestResults:      true
+              publishRunAttachments: false
               failTaskOnFailedTests: true
               testRunTitle:          '[Auto API] $(Build.BuildNumber)'
             displayName: 'Publish API test results (JUnit)'
 
+          # Artifact names include $(System.JobAttempt) to prevent collision on retries.
           - task: PublishPipelineArtifact@1
             condition: always()
             inputs:
               targetPath: '$(API_DIR)/playwright-report'
-              artifact:   'api-playwright-report'
+              artifact:   'api-playwright-report-attempt-$(System.JobAttempt)'
             displayName: 'Publish API HTML report'
 
           - task: PublishPipelineArtifact@1
             condition: always()
             inputs:
               targetPath: '$(API_DIR)/test-results'
-              artifact:   'api-test-results'
+              artifact:   'api-test-results-attempt-$(System.JobAttempt)'
             displayName: 'Publish API trace artifacts'

package/integrations/ado-powershell/scripts/sync-ado-titles.ps1

@@ -61,7 +61,7 @@ foreach ($entry in $mapping) {
                 Select-Object -First 1
 
     if (-not $specFile) {
-        Write-Warning "  [NOT FOUND] $($entry.specFile) — skipping WI $adoId"
+        Write-Warning "  [NOT FOUND] $($entry.specFile) - skipping WI $adoId"
         $skipped++
         continue
     }
@@ -84,7 +84,7 @@ foreach ($entry in $mapping) {
 
     if ($PSCmdlet.ShouldProcess("WI #$adoId", "Update title to: $newTitle")) {
         Invoke-RestMethod -Method Patch -Uri $patchUrl -Headers $headers -Body $body | Out-Null
-        Write-Host "  [SYNCED] WI #$adoId → $newTitle"
+        Write-Host "  [SYNCED] WI #$adoId -> $newTitle"
         $synced++
     }
 }