@keber/qa-framework 1.11.3 → 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/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++
     }
 }

package/integrations/playwright/README.md

@@ -1,4 +1,4 @@
-# Integration — Playwright
+# Integration - Playwright
 
 This directory documents how `@playwright/test` is configured within the
 `keber/qa-framework` opinionated setup.
@@ -40,9 +40,9 @@ suite execution.
 
 ## Debugging checklist
 
-1. `PWDEBUG=1 npx playwright test` — step through in inspector
-2. `--headed` — watch the browser
-3. `--trace on` — record full trace; open with `npx playwright show-trace`
+1. `PWDEBUG=1 npx playwright test` - step through in inspector
+2. `--headed` - watch the browser
+3. `--trace on` - record full trace; open with `npx playwright show-trace`
 4. Increase `actionTimeout` if the app has slow server-side rendering
 5. Add `await page.waitForLoadState('networkidle')` before assertions on
    dynamically loaded content

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "Reusable spec-driven QA framework for IDE-agent-assisted automated testing. Installable as an npm package. Provides structure, templates, agent instructions, and optional integrations for Playwright and Azure DevOps.",
   "keywords": [
     "qa",
@@ -21,7 +21,11 @@
     "postinstall": "node scripts/init.js --skip-if-exists",
     "init": "node scripts/cli.js init",
     "generate": "node scripts/cli.js generate",
-    "validate": "node scripts/cli.js validate"
+    "validate": "node scripts/cli.js validate",
+    "check-accents": "node scripts/check-spanish-accents.js",
+    "check-chars": "node scripts/check-forbidden-chars.js",
+    "test": "node --test test/*.test.js",
+    "version": "node scripts/sync-version.js && git add README.md .github/copilot-instructions.md"
   },
   "files": [
     "agent-instructions/",
@@ -36,7 +40,7 @@
     "qa-framework.config.json"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "peerDependencies": {
     "@keber/ado-qa": ">=1.0.0",

package/qa-framework.config.json

@@ -27,7 +27,7 @@
     "testCaseIdPattern": "TC-{MODULE}-{SUBMODULE}-{NUM}",
     "businessRuleIdPattern": "RN-{MODULE}-{NUM}",
     "workflowIdPattern": "FL-{MODULE}-{NUM}",
-    "defectIdPattern": "DEF-{NUM}",
+    "defectIdPattern": "DEF-{PREFIX}-{NUM}",
     "testNamingPattern": "[{ID}] {title} @{priority}",
     "timestampFormat": "YYYY-MM-DD_HH-MM-SS",
     "tcPriorityLevels": ["P0", "P1", "P2", "P3"]
@@ -42,6 +42,20 @@
     }
   ],
 
+  "parallelLanes": {
+    "enabled": false,
+    "lanes": [
+      {
+        "id": "1",
+        "account": "QA_USER",
+        "storageState": ".auth/user-default.json",
+        "mcpNamespace": null,
+        "runnerProject": "chromium",
+        "capabilities": []
+      }
+    ]
+  },
+
   "integrations": {
     "playwright": {
       "enabled": false,
@@ -69,7 +83,14 @@
       "variableGroup": "{{ADO_VARIABLE_GROUP}}",
       "pipelineFile": "qa/08-azure-integration/pipelines/azure-pipeline-qa.yml",
       "moduleRegistry": "qa/08-azure-integration/module-registry.json",
-      "reporterPackage": "@alex_neo/playwright-azure-reporter"
+      "reporterPackage": "@alex_neo/playwright-azure-reporter",
+      "sprintCycle": {
+        "enabled": false,
+        "sprintDurationDays": 8,
+        "manualTestingTimeboxDays": 2,
+        "dateFormat": "dd-mm-aaaa",
+        "timezone": "America/Santiago"
+      }
     }
   },
 

package/scripts/check-forbidden-chars.js

@@ -0,0 +1,187 @@
+#!/usr/bin/env node
+/**
+ * check-forbidden-chars.js
+ *
+ * Enforces the BLOCKING character-safety rule declared in
+ * .github/copilot-instructions.md: generated content must never carry typographic
+ * characters that survive a copy-paste but break on the way to a terminal, a CSV,
+ * a PowerShell script or an Azure DevOps field.
+ *
+ * Forbidden: em-dash (U+2014), en-dash (U+2013), horizontal ellipsis (U+2026),
+ * smart quotes (U+201C, U+201D, U+2018, U+2019) and arrows (U+2190-U+21FF).
+ * Each has an ASCII equivalent that renders identically everywhere.
+ *
+ * Latin Extended (U+00C0-U+024F) is explicitly NOT flagged: Spanish accents,
+ * n with tilde and u/o with umlaut are required orthography, not decoration.
+ * Emoji are not flagged either - they are outside the forbidden set.
+ *
+ * Unlike check-spanish-accents.js this scans .js and .ts as well as .md, because
+ * the generators under scripts/ embed these characters in template literals and
+ * console output that propagate into every consuming project.
+ *
+ * Usage:
+ *   node scripts/check-forbidden-chars.js <file|dir> [...]   check paths
+ *   node scripts/check-forbidden-chars.js --staged           check staged files
+ *   node scripts/check-forbidden-chars.js --report <paths>   print findings, never fail
+ *
+ * Exit codes: 0 = clean, 1 = at least one forbidden character, 2 = usage error.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { execFileSync } = require('child_process');
+
+// '.example' covers .env.example, which ships to consuming projects like any other
+// template. A BOM or an em-dash there is not cosmetic: some .env parsers read the
+// first key as QA_BASE_URL and silently fail to find it.
+const EXTENSIONS = ['.md', '.js', '.ts', '.ps1', '.example'];
+
+// Code point -> { name, replacement }. Arrows are handled by range below.
+const FORBIDDEN = {
+  0x2014: { name: 'em dash', replacement: ' - ' },
+  0x2013: { name: 'en dash', replacement: ' - ' },
+  0x2026: { name: 'horizontal ellipsis', replacement: '...' },
+  0x201c: { name: 'left double quotation mark', replacement: '"' },
+  0x201d: { name: 'right double quotation mark', replacement: '"' },
+  0x2018: { name: 'left single quotation mark', replacement: "'" },
+  0x2019: { name: 'right single quotation mark', replacement: "'" },
+};
+
+const ARROW_START = 0x2190;
+const ARROW_END = 0x21ff;
+
+// The two arrows with an obvious ASCII spelling; every other arrow in the block
+// has no single equivalent, so the report asks for a rewrite instead of guessing.
+const ARROW_REPLACEMENTS = {
+  0x2190: '<-',
+  0x2192: '->',
+};
+
+function describe(codePoint) {
+  if (FORBIDDEN[codePoint]) return FORBIDDEN[codePoint];
+  if (codePoint >= ARROW_START && codePoint <= ARROW_END) {
+    return {
+      name: 'arrow',
+      replacement: ARROW_REPLACEMENTS[codePoint] || 'an ASCII arrow such as -> or <-',
+    };
+  }
+  return null;
+}
+
+function hex(codePoint) {
+  return 'U+' + codePoint.toString(16).toUpperCase().padStart(4, '0');
+}
+
+/**
+ * Scan one file's text. Returns an array of findings; column is 1-based and
+ * counted in code points, so an astral character earlier on the line does not
+ * shift the reported position.
+ */
+function scanText(text, file) {
+  const findings = [];
+  const lines = text.split(/\r?\n/);
+
+  lines.forEach((line, lineIndex) => {
+    let column = 0;
+    for (const char of line) {
+      column += 1;
+      const codePoint = char.codePointAt(0);
+      const match = describe(codePoint);
+      if (!match) continue;
+      findings.push({
+        file,
+        line: lineIndex + 1,
+        column,
+        char,
+        codePoint,
+        name: match.name,
+        replacement: match.replacement,
+        text: line.trim(),
+      });
+    }
+  });
+
+  return findings;
+}
+
+function scanFile(file) {
+  return scanText(fs.readFileSync(file, 'utf8'), file);
+}
+
+// Archived copies of content this framework shipped in an earlier release. Their bytes
+// are the point: test/upgrade.test.js matches them against SHIPPED_SCAFFOLD_HASHES to
+// prove a real legacy installation is recognised as pristine. Rewriting a character in
+// one of them changes its hash and silently voids that proof, so they are read-only
+// history rather than authored content and the rule does not apply to them.
+const SKIP_DIRS = new Set(['node_modules', '.git', 'legacy-v1.11.3']);
+
+function collect(target) {
+  const stat = fs.statSync(target);
+  if (stat.isFile()) return EXTENSIONS.includes(path.extname(target)) ? [target] : [];
+  return fs.readdirSync(target).flatMap((entry) => {
+    if (SKIP_DIRS.has(entry)) return [];
+    return collect(path.join(target, entry));
+  });
+}
+
+function stagedFiles() {
+  const out = execFileSync(
+    'git',
+    ['diff', '--cached', '--name-only', '--diff-filter=ACM'],
+    { encoding: 'utf8' }
+  );
+  return out
+    .split('\n')
+    .map((s) => s.trim())
+    .filter((s) => s && EXTENSIONS.includes(path.extname(s)) && fs.existsSync(s));
+}
+
+function main(argv) {
+  const reportOnly = argv.includes('--report');
+  const args = argv.filter((a) => a !== '--report');
+
+  let files;
+  if (args.includes('--staged')) {
+    files = stagedFiles();
+  } else if (args.length) {
+    files = args.flatMap(collect);
+  } else {
+    console.error('usage: check-forbidden-chars.js <file|dir>... | --staged [--report]');
+    return 2;
+  }
+
+  const findings = files.flatMap(scanFile);
+
+  if (findings.length) {
+    const stream = reportOnly ? console.log : console.error;
+    stream(`\nForbidden characters (${findings.length} occurrence(s)):\n`);
+    for (const f of findings) {
+      stream(`  ${f.file}:${f.line}:${f.column}  "${f.char}" ${hex(f.codePoint)} ${f.name}`);
+      stream(`    use ${f.replacement}`);
+      stream(`    ${f.text}`);
+    }
+    if (!reportOnly) {
+      stream(
+        '\nThese characters break on the way to a terminal, a CSV export or an Azure' +
+        '\nDevOps field. Replace them with their ASCII equivalents rather than' +
+        '\nbypassing this check. Spanish accents are permitted and are never flagged.\n'
+      );
+      return 1;
+    }
+    return 0;
+  }
+
+  if (reportOnly) {
+    console.log(`check-forbidden-chars: ${files.length} file(s) checked, no findings.`);
+    return 0;
+  }
+
+  console.log(`check-forbidden-chars: ${files.length} file(s) checked, no violations.`);
+  return 0;
+}
+
+if (require.main === module) process.exit(main(process.argv.slice(2)));
+
+module.exports = { scanText, scanFile, main, EXTENSIONS, FORBIDDEN, ARROW_START, ARROW_END };