@keber/qa-framework 1.10.0 → 1.12.0

package/scripts/init.js

@@ -15,6 +15,9 @@
 const fs   = require('fs');
 const path = require('path');
 
+const { buildCommandContent, discoverSkillNames, commandFileName } = require('./lib/claude-commands');
+const { AGENT_NAMES, isSprintCycleEnabled, buildAgentContent, agentFileName } = require('./lib/claude-agents');
+
 // --- Parse args ---
 const args            = process.argv.slice(2);
 const configFlag      = args.indexOf('--config');
@@ -84,6 +87,7 @@ const topLevelFolders = [
   '04-test-data',
   '05-test-execution',
   '06-defects/open',
+  '06-defects/disputed',
   '06-defects/resolved',
   '07-automation/e2e/tests',
   '07-automation/e2e/tests/helpers/debug',
@@ -98,6 +102,18 @@ for (const folder of topLevelFolders) {
   console.log(`  [created] ${path.relative(cwd, fullPath)}/`);
 }
 
+// --- 06-defects/disputed/README.md ---
+writeIfMissing(path.join(qaRoot, '06-defects', 'disputed', 'README.md'),
+`# 06-defects/disputed/
+
+Use this folder for defects where QA has reproducible evidence but the business or
+development team disputes whether the observed behavior is actually a defect.
+
+A defect stays here while the functional decision is pending. Once the team reaches
+a formal conclusion, move the file to open/ (confirmed defect) or resolved/ (accepted
+behavior or won't fix).
+`);
+
 // --- qa/README.md ---
 const qaReadmeTemplate = path.resolve(__dirname, '..', 'templates', 'qa-readme.md');
 if (fs.existsSync(qaReadmeTemplate)) {
@@ -113,20 +129,27 @@ if (fs.existsSync(qaReadmeTemplate)) {
 // --- qa/memory/INDEX.md ---
 const memoryDir = path.join(qaRoot, 'memory');
 writeIfMissing(path.join(memoryDir, 'INDEX.md'),
-`# Memory Index — ${config.project?.displayName ?? config.project?.name ?? 'Project'}
+`# Memory Index - ${config.project?.displayName ?? config.project?.name ?? 'Project'}
 
 > The agent reads this file first before loading any memory file.
 > Add a row here whenever you create or update a file in this directory.
 
 | File | Topic | When to load |
 |---|---|---|
-
-_No memory files yet. Add files to this directory and register them above._
+| \`ci-pipeline-findings.md\` | CI pipeline issues, root causes, applied fixes, failure triage categories | Diagnosing CI failures; reviewing pipeline changes |
+| \`e2e-stabilization-patterns.md\` | Flakiness patterns, crash-recovery techniques, strict-mode conflicts, reference timeouts | Investigating intermittent failures; refactoring fragile specs |
+| \`data-volatility-strategies.md\` | Strategies for handling volatile test data (filter values, row counts, search inputs) | Fixing hardcoded-data failures; choosing an assertion resilience approach |
 `);
 
+// --- qa/memory template files ---
+const memorySrc = path.resolve(__dirname, '..', 'templates', 'memory');
+for (const file of ['ci-pipeline-findings.md', 'e2e-stabilization-patterns.md', 'data-volatility-strategies.md']) {
+  writeIfMissing(path.join(memoryDir, file), fs.readFileSync(path.join(memorySrc, file), 'utf8'));
+}
+
 // --- 03-test-cases README (optional directory marker) ---
 writeIfMissing(path.join(qaRoot, '03-test-cases', 'README.md'),
-`# 03-test-cases/ — Optional Standalone Test Cases
+`# 03-test-cases/ - Optional Standalone Test Cases
 
 > **v1.7.0+:** The primary location for test cases (with detailed steps) is now
 > \`qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{project}-Sprint-{N}-{module}.md\`.
@@ -178,7 +201,7 @@ for (const mod of modules) {
 
   for (const sub of submodules) {
     const subKey = sub.key ?? sub.name.toLowerCase().replace(/\s+/g, '-');
-    const subDir = path.join(qaRoot, moduleKey, subKey);
+    const subDir = path.join(qaRoot, '01-specifications', moduleKey, subKey);
     fs.mkdirSync(subDir, { recursive: true });
 
     for (const specFile of SPEC_FILES) {
@@ -225,9 +248,22 @@ for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', '
     console.log(`  [created] ${path.relative(cwd, dest)}`);
   }
 }
+// Lane scripts: the lane lock plus its config reader and global-setup guards. Plain
+// CommonJS so they run as a CLI and stay testable with `node --test` without pulling
+// in a TypeScript test runner.
+const laneScriptsDir = path.join(e2eScaffoldDir, 'scripts');
+fs.mkdirSync(laneScriptsDir, { recursive: true });
+for (const file of ['lane-config.js', 'lane-lock.js', 'global-setup-guards.js']) {
+  const dest = path.join(laneScriptsDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(scaffoldSrc, 'scripts', file), dest);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
+  }
+}
+
 const fixturesDir = path.join(e2eScaffoldDir, 'fixtures');
 fs.mkdirSync(fixturesDir, { recursive: true });
-for (const file of ['auth.ts', 'test-helpers.ts']) {
+for (const file of ['auth.ts', 'test-helpers.ts', 'base.ts']) {
   const dest = path.join(fixturesDir, file);
   if (!fs.existsSync(dest)) {
     fs.copyFileSync(path.join(scaffoldSrc, 'fixtures', file), dest);
@@ -235,9 +271,26 @@ for (const file of ['auth.ts', 'test-helpers.ts']) {
   }
 }
 
-// --- Integration + Load test placeholders ---
-writeIfMissing(path.join(automationDir, 'integration', 'README.md'),
-`# Integration Tests\n\n> Placeholder for API/integration tests (k6, JMeter, Azure Load Testing, etc.).\n> Each tool gets its own subdirectory.\n`);
+// --- Integration scaffold (lives in 07-automation/integration/) ---
+const integrationDir      = path.join(automationDir, 'integration');
+const integrationScaffold = path.resolve(__dirname, '..', 'templates', 'integration-scaffold');
+fs.mkdirSync(integrationDir, { recursive: true });
+for (const file of ['package.json', 'playwright.config.ts', 'global-setup.ts', 'README.md', '.env.example']) {
+  const dest = path.join(integrationDir, file);
+  if (!fs.existsSync(dest)) {
+    fs.copyFileSync(path.join(integrationScaffold, file), dest);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
+  }
+}
+const integrationTestsDir = path.join(integrationDir, 'tests');
+fs.mkdirSync(integrationTestsDir, { recursive: true });
+const exampleSpec = path.join(integrationTestsDir, 'example.spec.ts');
+if (!fs.existsSync(exampleSpec)) {
+  fs.copyFileSync(path.join(integrationScaffold, 'tests', 'example.spec.ts'), exampleSpec);
+  console.log(`  [created] ${path.relative(cwd, exampleSpec)}`);
+}
+
+// --- Load test placeholder ---
 writeIfMissing(path.join(automationDir, 'load', 'README.md'),
 `# Load Tests\n\n> Placeholder for load and performance tests.\n> Each tool gets its own subdirectory (e.g. k6/, jmeter/).\n`);
 
@@ -246,7 +299,7 @@ const adoDir = path.join(qaRoot, '08-azure-integration');
 writeIfMissing(path.join(adoDir, 'README.md'), `# ADO Integration\n\nSee keber/qa-framework integrations/ado-powershell/ for setup instructions.\n`);
 writeIfMissing(path.join(adoDir, 'module-registry.json'), JSON.stringify({ modules: [] }, null, 2));
 
-// --- Skills → .github/skills/ ---
+// --- Skills -> .github/skills/ ---
 const skillsSrc = path.resolve(__dirname, '..', 'skills');
 const skillsDest = path.join(cwd, '.github', 'skills');
 fs.mkdirSync(skillsDest, { recursive: true });
@@ -261,7 +314,7 @@ if (fs.existsSync(skillsSrc)) {
   }
 }
 
-// --- QA structure guide → qa/QA-STRUCTURE-GUIDE.md ---
+// --- QA structure guide -> qa/QA-STRUCTURE-GUIDE.md ---
 const structureGuideSrc  = path.resolve(__dirname, '..', 'docs', 'folder-structure-guide.md');
 const structureGuideDest = path.join(qaRoot, 'QA-STRUCTURE-GUIDE.md');
 if (fs.existsSync(structureGuideSrc)) {
@@ -272,40 +325,38 @@ if (fs.existsSync(structureGuideSrc)) {
 const githubDir         = path.join(cwd, '.github');
 const copilotInstrPath  = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
 
-// Detect whether the ado-qa skill is available (installed or already copied)
-const adoQaInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@keber', 'ado-qa'))
-                    || fs.existsSync(path.join(cwd, 'node_modules', 'ado-qa'));
-const adoSkillReady  = fs.existsSync(path.join(cwd, '.github', 'skills', 'ado-qa'));
-const adoAvailable   = adoQaInstalled || adoSkillReady;
-
-const adoSection = adoAvailable
-  ? `## Azure DevOps integration (ado-qa)
-
-The \`ado-qa\` skill is installed. Load it in PowerShell before any ADO operation:
-\`\`\`powershell
-. .github/skills/ado-qa/load.ps1
-\`\`\`
-Refer to \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` for the full ADO workflow.
-
-`
-  : `## Azure DevOps integration (not installed)
-
-> ⚠️ **Agent note:** \`ado-qa\` is not installed in this project.
-> To enable Azure DevOps integration (query Work Items, Test Plans, create bugs, etc.) run:
-> \`\`\`bash
-> npm install github:keber/ado-qa
-> \`\`\`
-> This will automatically copy the ADO skills to \`.github/skills/\` via postinstall.
-
-`;
-
 const instrTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.instructions.md');
 const copilotInstrContent = fs.readFileSync(instrTemplatePath, 'utf8')
-  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0')
-  .replace('{{ADO_SECTION}}', adoSection);
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
-// --- AGENT-NEXT-STEPS.md — readable by the agent after install ---
+// --- .claude/commands/qa-*.md - thin wrappers pointing at .github/skills/ ---
+const claudeCommandsDest = path.join(cwd, '.claude', 'commands');
+fs.mkdirSync(claudeCommandsDest, { recursive: true });
+for (const skillName of discoverSkillNames(skillsSrc)) {
+  writeIfMissing(path.join(claudeCommandsDest, commandFileName(skillName)), buildCommandContent(skillName));
+}
+
+// --- .claude/rules/qa-framework.md - always-loaded rules (Claude Code equivalent of applyTo: '**') ---
+const claudeRulesPath  = path.join(cwd, '.claude', 'rules', 'qa-framework.md');
+const rulesTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.rules.md');
+const claudeRulesContent = fs.readFileSync(rulesTemplatePath, 'utf8')
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
+writeIfMissing(claudeRulesPath, claudeRulesContent);
+
+// --- .claude/agents/qa-*.md - optional ANALISIS/PLAN sprint-cycle mode (Claude Code only) ---
+// Gated by integrations.azureDevOps.sprintCycle.enabled. No .github/ equivalent: Claude
+// Code subagents with per-agent tools/model frontmatter have no Copilot counterpart.
+if (isSprintCycleEnabled(config)) {
+  const templatesDir = path.resolve(__dirname, '..', 'templates');
+  const claudeAgentsDest = path.join(cwd, '.claude', 'agents');
+  fs.mkdirSync(claudeAgentsDest, { recursive: true });
+  for (const agentName of AGENT_NAMES) {
+    writeIfMissing(path.join(claudeAgentsDest, agentFileName(agentName)), buildAgentContent(agentName, templatesDir, config));
+  }
+}
+
+// --- AGENT-NEXT-STEPS.md - readable by the agent after install ---
 const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 
 > This file was generated automatically by the postinstall script.
@@ -315,6 +366,7 @@ const nextStepsContent = `# ✅ @keber/qa-framework installed successfully
 
 - \`qa/\` folder structure with spec templates and agent instructions
 - \`.github/instructions/qa-framework.instructions.md\` with QA agent behavior rules (framework-owned, safe to upgrade)
+- \`.claude/rules/qa-framework.md\` and \`.claude/commands/qa-*.md\` - equivalent Claude Code artifacts (framework-owned, safe to upgrade)
 
 ## Required next steps
 
@@ -328,15 +380,21 @@ Edit \`qa/qa-framework.config.json\` and add your project modules under the \`"m
 npm install @keber/ado-qa
 \`\`\`
 
-**Playwright automation:**
+**Playwright E2E automation:**
 \`\`\`bash
 npm install @playwright/test
 cd qa/07-automation/e2e && npm install && npx playwright install chromium
 \`\`\`
 
+**Playwright API/integration automation:**
+\`\`\`bash
+cd qa/07-automation/integration && npm install
+\`\`\`
+
 ### 3. Credentials
-- Copy \`qa/07-automation/e2e/.env.example\` → \`qa/07-automation/e2e/.env\` and fill in credentials
-- Add \`qa/07-automation/e2e/.env\` and \`qa/07-automation/e2e/.auth/\` to \`.gitignore\`
+- Copy \`qa/07-automation/e2e/.env.example\` -> \`qa/07-automation/e2e/.env\` and fill in credentials
+- Copy \`qa/07-automation/integration/.env.example\` -> \`qa/07-automation/integration/.env\` and fill in credentials
+- Add both \`.env\` files and both \`.auth/\` folders to \`.gitignore\`
 `;
 const nextStepsPath = path.join(qaRoot, 'AGENT-NEXT-STEPS.md');
 writeIfMissing(nextStepsPath, nextStepsContent);
@@ -347,12 +405,17 @@ const adoQaInstalledFinal = fs.existsSync(path.join(cwd, 'node_modules', '@keber
 const azureReporterInstalled = fs.existsSync(path.join(cwd, 'node_modules', '@alex_neo', 'playwright-azure-reporter'));
 
 console.log('');
-console.log('  @keber/qa-framework — scaffold complete');
+console.log('  @keber/qa-framework - scaffold complete');
 console.log('  ----------------------------------------');
 console.log('  Installed:');
 console.log('    qa/                    QA directory structure + spec templates');
 console.log('    .github/skills/        QA agent skills (8 stages)');
 console.log('    .github/instructions/  qa-framework.instructions.md');
+console.log('    .claude/commands/      qa-*.md (Claude Code slash commands)');
+console.log('    .claude/rules/         qa-framework.md (Claude Code always-loaded rules)');
+if (isSprintCycleEnabled(config)) {
+  console.log('    .claude/agents/        qa-analisis/qa-plan/qa-asesoria/qa-informe-resultados.md (ANALISIS/PLAN mode)');
+}
 console.log('');
 console.log('  Optional integrations:');
 if (playwrightInstalled) {

package/scripts/lib/claude-agents.js

@@ -0,0 +1,78 @@
+'use strict';
+
+/**
+ * scripts/lib/claude-agents.js - Generate .claude/agents/qa-*.md sprint-cycle subagents
+ *
+ * Optional ANALISIS/PLAN mode, gated by integrations.azureDevOps.sprintCycle.enabled in
+ * qa-framework.config.json. Claude Code only - subagents with per-agent tools/model
+ * frontmatter have no GitHub Copilot equivalent, so no .github/ counterpart is generated.
+ *
+ * Placeholders are resolved from config.integrations.azureDevOps.sprintCycle, falling back
+ * to neutral defaults when a field (or the whole config section) is absent.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const AGENT_NAMES = ['qa-analisis', 'qa-plan', 'qa-asesoria', 'qa-informe-resultados'];
+
+const DEFAULT_SPRINT_CYCLE = {
+  sprintDurationDays: 8,
+  manualTestingTimeboxDays: 2,
+  dateFormat: 'dd-mm-aaaa',
+  timezone: 'America/Santiago',
+};
+
+const LOCALE_LANGUAGE_LABELS = {
+  es: 'espanol',
+  'es-cl': 'espanol de Chile',
+  'es-mx': 'espanol de Mexico',
+  'es-ar': 'espanol de Argentina',
+  en: 'English',
+};
+
+function isSprintCycleEnabled(config) {
+  return Boolean(config?.integrations?.azureDevOps?.sprintCycle?.enabled);
+}
+
+function resolveLocaleLanguageLabel(locale) {
+  if (!locale) return 'espanol';
+  return LOCALE_LANGUAGE_LABELS[locale.toLowerCase()] ?? locale;
+}
+
+function buildPlaceholders(config) {
+  const sprintCycle = { ...DEFAULT_SPRINT_CYCLE, ...(config?.integrations?.azureDevOps?.sprintCycle ?? {}) };
+  const project = config?.project ?? {};
+
+  return {
+    '{{PROJECT_NAME}}': project.name ?? '{{PROJECT_NAME}}',
+    '{{PROJECT_DISPLAY_NAME}}': project.displayName ?? project.name ?? '{{PROJECT_DISPLAY_NAME}}',
+    '{{SPRINT_DURATION_DAYS}}': String(sprintCycle.sprintDurationDays),
+    '{{MANUAL_TESTING_TIMEBOX_DAYS}}': String(sprintCycle.manualTestingTimeboxDays),
+    '{{DATE_FORMAT}}': sprintCycle.dateFormat,
+    '{{TIMEZONE}}': sprintCycle.timezone,
+    '{{LOCALE_LANGUAGE_LABEL}}': resolveLocaleLanguageLabel(config?.conventions?.locale ?? config?.conventions?.language),
+    '{{DEFECT_ID_PREFIX}}': config?.project?.name ? config.project.name.toUpperCase().replace(/[^A-Z0-9]/g, '-') : 'PROJ',
+  };
+}
+
+function buildAgentContent(agentName, templatesDir, config) {
+  const templatePath = path.join(templatesDir, 'agents', `${agentName}.md`);
+  let content = fs.readFileSync(templatePath, 'utf8');
+  const placeholders = buildPlaceholders(config);
+  for (const [placeholder, value] of Object.entries(placeholders)) {
+    content = content.split(placeholder).join(value);
+  }
+  return content;
+}
+
+function agentFileName(agentName) {
+  return `${agentName}.md`;
+}
+
+module.exports = {
+  AGENT_NAMES,
+  isSprintCycleEnabled,
+  buildAgentContent,
+  agentFileName,
+};

package/scripts/lib/claude-commands.js

@@ -0,0 +1,56 @@
+'use strict';
+
+/**
+ * scripts/lib/claude-commands.js - Generate .claude/commands/qa-{name}.md thin wrappers
+ *
+ * Each generated command points back at the corresponding SKILL.md as the single
+ * source of truth (no content duplication, no drift). Skills are discovered
+ * dynamically from the filesystem, never hardcoded, so a newly added skill
+ * under skills/ is picked up automatically by init.js and upgrade.js.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Stage prerequisites mirrored from templates/qa-framework.instructions.md pipeline table.
+// Skills not listed here (e.g. a future addition) still get a valid command with no
+// prerequisite line, and this codebase does not need updating for the command to work.
+const STAGE_PREREQUISITES = {
+  'qa-module-analysis': 'Prerequisite: None - this is the first stage of the QA pipeline.',
+  'qa-spec-generation': 'Prerequisite: `00-inventory.md` exists.',
+  'qa-test-plan': 'Prerequisite: `05-test-scenarios.md` exists.',
+  'qa-test-cases': 'Prerequisite: Test plan exists.',
+  'qa-automation': 'Prerequisite: Specs approved, no PENDING-CODE.',
+  'qa-test-stabilization': 'Prerequisite: Failing or flaky tests exist in `qa/07-automation/e2e/`.',
+  'qa-maintenance': 'Prerequisite: Application change delivered.',
+  'qa-ado-integration': 'Prerequisite: ADO enabled in `qa/qa-framework.config.json`.',
+};
+
+function buildCommandContent(skillName) {
+  const prerequisite = STAGE_PREREQUISITES[skillName];
+  const lines = [
+    `Read the full skill at \`.github/skills/${skillName}/SKILL.md\` FIRST, then follow its instructions exactly.`,
+  ];
+  if (prerequisite) {
+    lines.push('', prerequisite);
+  }
+  return `${lines.join('\n')}\n`;
+}
+
+function discoverSkillNames(skillsSrcDir) {
+  if (!fs.existsSync(skillsSrcDir)) return [];
+  return fs.readdirSync(skillsSrcDir, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+function commandFileName(skillName) {
+  return `${skillName}.md`;
+}
+
+module.exports = {
+  buildCommandContent,
+  discoverSkillNames,
+  commandFileName,
+};

package/scripts/sync-version.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const rootDir = path.resolve(__dirname, '..');
+const pkg = require(path.join(rootDir, 'package.json'));
+const version = pkg.version;
+
+const targets = [
+  path.join(rootDir, 'README.md'),
+  path.join(rootDir, '.github', 'copilot-instructions.md'),
+];
+
+// templates/qa-framework.instructions.md and templates/qa-framework.rules.md contain a
+// literal {{VERSION}} placeholder substituted by init.js/upgrade.js in the consumer
+// project at install/upgrade time. That placeholder is NOT a hardcoded version string
+// and must never be touched here.
+
+const versionPattern = /v\d+\.\d+\.\d+/;
+
+for (const filePath of targets) {
+  const original = fs.readFileSync(filePath, 'utf8');
+
+  if (!versionPattern.test(original)) {
+    throw new Error(`sync-version: no version string found in ${filePath}`);
+  }
+
+  const updated = original.replace(versionPattern, `v${version}`);
+
+  if (updated !== original) {
+    fs.writeFileSync(filePath, updated, 'utf8');
+    console.log(`sync-version: updated ${path.relative(rootDir, filePath)} -> v${version}`);
+  }
+}