@keber/qa-framework 1.10.0 → 1.12.0

package/scripts/upgrade.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * scripts/upgrade.js — Upgrade framework-owned files in an existing project
+ * scripts/upgrade.js - Upgrade framework-owned files in an existing project
  *
  * Usage:
  *   qa-framework upgrade
@@ -27,7 +27,37 @@
  *     - qa/02-test-plans/manual/     -> qa/02-test-plans/sprints/legacy-manual/
  *     - qa/02-test-plans/*.md        -> qa/02-test-plans/sprints/legacy/
  *     - Creates qa/02-test-plans/sprints/ if absent
- *     - Creates qa/03-test-cases/README.md optional marker if absent *
+ *     - Creates qa/03-test-cases/README.md optional marker if absent
+ *
+ *   MIGRATES (v1.11.x -> v1.12.0, lane-aware automation scaffold):
+ *     Installs the lane scaffold only where it cannot break working user code.
+ *     A file counts as framework-owned ("pristine") when its normalised sha256
+ *     matches one this framework actually shipped; otherwise it is user-owned.
+ *
+ *     ATOMIC GROUP (all installed, or none - config/global-setup require() the scripts):
+ *       - qa/07-automation/e2e/scripts/lane-config.js         (new in v1.12.0)
+ *       - qa/07-automation/e2e/scripts/lane-lock.js           (new in v1.12.0)
+ *       - qa/07-automation/e2e/scripts/global-setup-guards.js (new in v1.12.0)
+ *       - qa/07-automation/e2e/playwright.config.ts
+ *       - qa/07-automation/e2e/global-setup.ts
+ *       If any member is user-owned the whole group is skipped with a warning and
+ *       the upgrade continues; the project keeps its working setup rather than
+ *       being left half-migrated.
+ *
+ *     PER FILE (leaf modules - a mixed state is still coherent):
+ *       - qa/07-automation/e2e/fixtures/{auth,base,test-helpers}.ts
+ *       - qa/07-automation/integration/{playwright.config.ts,global-setup.ts}
+ *       - .env.example in both scaffolds (reference template only; your .env
+ *         is never touched)
+ *       Pristine -> overwritten. User-owned -> kept, with a warning.
+ *
+ *     REPORTS only (never patched):
+ *       - .fill(password) in any .ts under e2e/ or integration/ - leaks the
+ *         password into Playwright traces. See "Pattern 7" in
+ *         .github/skills/qa-automation/references/patterns.md. Not auto-fixed:
+ *         the surrounding code differs per project and a bad rewrite of a
+ *         working login is worse than the finding.
+ *
  *   NEVER touches (project-owned):
  *     - qa/01-specifications/       <- Your specs
  *     - qa/02-test-plans/           <- Your test plans
@@ -46,6 +76,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');
+
 const args   = process.argv.slice(2);
 const dryRun = args.includes('--dry-run');
 
@@ -70,6 +103,52 @@ const githubDir  = path.join(cwd, '.github');
 const skillsDest = path.join(githubDir, 'skills');
 const skillsSrc  = path.resolve(__dirname, '..', 'skills');
 
+// Normalised sha256 of every version of these scaffold files that this framework has
+// shipped (v1.8.0 through v1.11.3). A project file matching one of these was written
+// by the framework and never edited, so v1.12.0 may safely replace it. Anything else
+// is user-owned. Regenerate by hashing `git show <tag>:templates/<key>` for each tag.
+//
+// Deliberately hash-based rather than version-based: the frameworkVersion recorded in
+// real installations is unreliable (observed values include 1.1.3 and 1.0.0, neither
+// of which corresponds to a released scaffold).
+const SHIPPED_SCAFFOLD_HASHES = {
+  'automation-scaffold/playwright.config.ts': [
+    '948635c118553e293447930ba3dcff9155446718554dd3bbcffac2720baebba1',
+    'f145fda0a7215942b5431a779188609f8958e51a048b161ede605576efba3ef8',
+  ],
+  'automation-scaffold/global-setup.ts': [
+    '077580914881ee71ac082d47579dc4cffa01e8348b0744fced6b8de2863e0bd1',
+    '7b3e7ca54929e525055d19ba8cd9643de722c7092c67b1a2e273072dd712ec7a',
+  ],
+  'automation-scaffold/.env.example': [
+    '18fab7c165085a4a585a6911b42c49b97177265d46261c8362c3508a7436c65c',
+    '29dc3a97e42350fbe7a16681837ba8db2a539574f8aa86fe269204bc3081bff9',
+  ],
+  'automation-scaffold/fixtures/auth.ts': [
+    'a856df26d80d521a0ad349879096698191ed6a2f919fac96d85980ab1d435c3e',
+  ],
+  'automation-scaffold/fixtures/base.ts': [
+    '7c52ea17fad732825e327af59a7f0f3bf53db166f7191932ae51c97fd2825a39',
+  ],
+  'automation-scaffold/fixtures/test-helpers.ts': [
+    'e2298972dea50e7df54265a7a94a232c0ff35c969f1b8778929079cfa2a1a541',
+  ],
+  // Introduced in v1.12.0 - never shipped before, so an existing copy in a project is
+  // always user-authored (two live installations hand-wrote their own lane-lock.js).
+  'automation-scaffold/scripts/lane-config.js': [],
+  'automation-scaffold/scripts/lane-lock.js': [],
+  'automation-scaffold/scripts/global-setup-guards.js': [],
+  'integration-scaffold/playwright.config.ts': [
+    '7276ed4fda85f80e37381257bc559f4bb48055d359858f69f6b838f3671a9e2d',
+  ],
+  'integration-scaffold/global-setup.ts': [
+    'f63f9588c4746a16e46345d1d4b781f2905b652481d563cfc075d9d8c8481bde',
+  ],
+  'integration-scaffold/.env.example': [
+    '671461d7dc9883505cec314aefa1129a336b6a03b31a0eb2eb2ede2adda7c4ac',
+  ],
+};
+
 const updated  = [];
 const skipped  = [];
 const warnings = [];
@@ -78,32 +157,58 @@ console.log(`\n[qa-framework/upgrade] ${dryRun ? '(dry-run) ' : ''}Upgrading fra
 console.log(`[qa-framework/upgrade] Project root: ${cwd}\n`);
 
 // ---------------------------------------------------------------------------
-// 1. .github/skills/ — always overwrite (framework-owned)
+// 1. .github/skills/ - always overwrite (framework-owned)
 // ---------------------------------------------------------------------------
 if (!fs.existsSync(skillsSrc)) {
-  warnings.push('skills/ source directory not found in package — skipping skill install');
+  warnings.push('skills/ source directory not found in package - skipping skill install');
 } else {
   fs.mkdirSync(skillsDest, { recursive: true });
   copyDirForce(skillsSrc, skillsDest);
 }
 
 // ---------------------------------------------------------------------------
-// 2. .github/instructions/qa-framework.instructions.md — overwrite (framework-owned)
+// 2. .github/instructions/qa-framework.instructions.md - overwrite (framework-owned)
 // ---------------------------------------------------------------------------
 const copilotInstrPath = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
 const instrTemplatePath = path.resolve(__dirname, '..', 'templates', 'qa-framework.instructions.md');
 const copilotContent = fs.readFileSync(instrTemplatePath, 'utf8')
-  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0')
-  .replace('{{ADO_SECTION}}', '');
+  .replace('{{VERSION}}', config.frameworkVersion ?? '1.0.0');
 forceWrite(copilotInstrPath, copilotContent);
 
+// ---------------------------------------------------------------------------
+// 2a. .claude/commands/qa-*.md and .claude/rules/qa-framework.md - overwrite (framework-owned)
+// ---------------------------------------------------------------------------
+const claudeCommandsDest = path.join(cwd, '.claude', 'commands');
+for (const skillName of discoverSkillNames(skillsSrc)) {
+  forceWrite(path.join(claudeCommandsDest, commandFileName(skillName)), buildCommandContent(skillName));
+}
+
+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');
+forceWrite(claudeRulesPath, claudeRulesContent);
+
+// ---------------------------------------------------------------------------
+// 2c. .claude/agents/qa-*.md - optional ANALISIS/PLAN sprint-cycle mode (Claude Code only)
+//     Gated by integrations.azureDevOps.sprintCycle.enabled. Framework-owned when the
+//     flag is on; never generated (and never deleted if it was hand-authored) otherwise.
+// ---------------------------------------------------------------------------
+if (isSprintCycleEnabled(config)) {
+  const templatesDir = path.resolve(__dirname, '..', 'templates');
+  const claudeAgentsDest = path.join(cwd, '.claude', 'agents');
+  for (const agentName of AGENT_NAMES) {
+    forceWrite(path.join(claudeAgentsDest, agentFileName(agentName)), buildAgentContent(agentName, templatesDir, config));
+  }
+}
+
 // ---------------------------------------------------------------------------
 // 2b. Migration: strip QA Framework section from old copilot-instructions.md
 //
 // Handles all cases:
-//   A. File has custom instructions + QA section  → keep custom, strip QA section
-//   B. File has ONLY QA section (any version)     → delete the file
-//   C. File does not mention QA Framework         → leave untouched
+//   A. File has custom instructions + QA section  -> keep custom, strip QA section
+//   B. File has ONLY QA section (any version)     -> delete the file
+//   C. File does not mention QA Framework         -> leave untouched
 //
 // The QA section always starts with "# QA Framework Instructions" across all
 // previous versions, so that heading is the reliable split point.
@@ -119,22 +224,22 @@ if (fs.existsSync(oldCopilotPath)) {
     const before = oldContent.slice(0, qaIdx).replace(/\s*\n---\s*$/, '').trim();
 
     if (before.length === 0) {
-      // Case B: file contained only QA Framework content → delete it
+      // Case B: file contained only QA Framework content -> delete it
       if (!dryRun) fs.unlinkSync(oldCopilotPath);
       updated.push(oldCopilotPath);
-      console.log(`  [deleted]  .github/copilot-instructions.md (contained only QA Framework rules — now in .github/instructions/qa-framework.instructions.md)`);
+      console.log(`  [deleted]  .github/copilot-instructions.md (contained only QA Framework rules - now in .github/instructions/qa-framework.instructions.md)`);
     } else {
-      // Case A: file had custom content too → write back only the custom part
+      // Case A: file had custom content too -> write back only the custom part
       if (!dryRun) fs.writeFileSync(oldCopilotPath, before + '\n', 'utf8');
       updated.push(oldCopilotPath);
-      console.log(`  [cleaned]  .github/copilot-instructions.md — removed QA Framework section, kept custom instructions`);
+      console.log(`  [cleaned]  .github/copilot-instructions.md - removed QA Framework section, kept custom instructions`);
     }
   }
-  // Case C: no QA marker found → leave untouched (no log noise)
+  // Case C: no QA marker found -> leave untouched (no log noise)
 }
 
 // ---------------------------------------------------------------------------
-// 3. qa/QA-STRUCTURE-GUIDE.md — overwrite (framework doc)
+// 3. qa/QA-STRUCTURE-GUIDE.md - overwrite (framework doc)
 // ---------------------------------------------------------------------------
 const structureGuideSrc  = path.resolve(__dirname, '..', 'docs', 'folder-structure-guide.md');
 const structureGuideDest = path.join(qaRoot, 'QA-STRUCTURE-GUIDE.md');
@@ -175,6 +280,22 @@ for (const file of scaffoldFiles) {
   }
 }
 
+// 5a.1. Ensure the refreshed fixtures scaffold exists.
+const scaffoldFixturesDir = path.join(e2eDir, 'fixtures');
+const fixtureFiles = ['auth.ts', 'test-helpers.ts', 'base.ts'];
+for (const file of fixtureFiles) {
+  const oldPath = path.join(automationDir, 'fixtures', file);
+  const newPath = path.join(scaffoldFixturesDir, file);
+  if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+    if (!dryRun) {
+      fs.mkdirSync(scaffoldFixturesDir, { recursive: true });
+      fs.renameSync(oldPath, newPath);
+    }
+    updated.push(newPath);
+    console.log(`  [migrated] fixtures/${file} -> e2e/fixtures/${file}`);
+  }
+}
+
 // 5b. fixtures/: 07-automation/fixtures/ -> 07-automation/e2e/fixtures/
 const oldFixturesDir = path.join(automationDir, 'fixtures');
 const newFixturesDir = path.join(e2eDir, 'fixtures');
@@ -205,23 +326,40 @@ if (fs.existsSync(e2eDir)) {
       console.log(`  [migrated] e2e/${entry.name}/ -> e2e/tests/${entry.name}/`);
     } else {
       warnings.push(
-        `Cannot migrate e2e/${entry.name}/ — target e2e/tests/${entry.name}/ already exists. Merge manually.`
+        `Cannot migrate e2e/${entry.name}/ - target e2e/tests/${entry.name}/ already exists. Merge manually.`
       );
     }
   }
 }
 
-// 5d. Create integration/ and load/ placeholders if missing.
-const integrationReadme = path.join(automationDir, 'integration', 'README.md');
-const loadReadme        = path.join(automationDir, 'load', 'README.md');
+// 5d. Create integration scaffold if missing (uses template; existing files are never overwritten).
+const integrationDir      = path.join(automationDir, 'integration');
+const integrationScaffold = path.resolve(__dirname, '..', 'templates', 'integration-scaffold');
+const integrationReadme   = path.join(integrationDir, 'README.md');
+const loadReadme          = path.join(automationDir, 'load', 'README.md');
 if (!fs.existsSync(integrationReadme)) {
   if (!dryRun) {
-    fs.mkdirSync(path.dirname(integrationReadme), { recursive: true });
-    fs.writeFileSync(integrationReadme,
-      '# Integration Tests\n\n> Placeholder for API/integration tests (k6, JMeter, Azure Load Testing, etc.).\n> Each tool gets its own subdirectory.\n', 'utf8');
+    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);
+        updated.push(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);
+      updated.push(exampleSpec);
+      console.log(`  [created] ${path.relative(cwd, exampleSpec)}`);
+    }
+  } else {
+    updated.push(integrationReadme);
+    console.log(`  [created] ${path.relative(cwd, integrationReadme)}`);
   }
-  updated.push(integrationReadme);
-  console.log(`  [created] ${path.relative(cwd, integrationReadme)}`);
 }
 if (!fs.existsSync(loadReadme)) {
   if (!dryRun) {
@@ -243,7 +381,7 @@ if (fs.existsSync(playwrightConfigPath)) {
   if (/testDir\s*:\s*['"]\.['"]/.test(cfg)) {
     cfg = cfg.replace(/testDir\s*:\s*['"]\.['"]/g, "testDir:  './tests'");
     cfgChanged = true;
-    console.log(`  [patched] e2e/playwright.config.ts — testDir: '.' -> './tests'`);
+    console.log(`  [patched] e2e/playwright.config.ts - testDir: '.' -> './tests'`);
   }
 
   // Inject testIgnore after testDir line if not present
@@ -253,7 +391,7 @@ if (fs.existsSync(playwrightConfigPath)) {
       "$1  testIgnore: ['**/helpers/debug/**', '**/seeds/**'],\n"
     );
     cfgChanged = true;
-    console.log(`  [patched] e2e/playwright.config.ts — added testIgnore`);
+    console.log(`  [patched] e2e/playwright.config.ts - added testIgnore`);
   }
 
   if (cfgChanged) {
@@ -312,7 +450,7 @@ if (fs.existsSync(testPlansDir)) {
         updated.push(newFile);
         console.log(`  [migrated] 02-test-plans/${entry.name} -> 02-test-plans/sprints/legacy/${entry.name}`);
       } else {
-        warnings.push(`Cannot migrate 02-test-plans/${entry.name} — target already exists. Move manually.`);
+        warnings.push(`Cannot migrate 02-test-plans/${entry.name} - target already exists. Move manually.`);
       }
     }
   }
@@ -331,7 +469,7 @@ if (!fs.existsSync(testCasesReadme)) {
   if (!dryRun) {
     fs.mkdirSync(path.dirname(testCasesReadme), { recursive: true });
     fs.writeFileSync(testCasesReadme,
-      '# 03-test-cases/ — Optional Standalone Test Cases\n\n' +
+      '# 03-test-cases/ - Optional Standalone Test Cases\n\n' +
       '> **v1.7.0+:** The primary location for test cases (with detailed steps) is now\n' +
       '> `qa/02-test-plans/sprints/Sprint-{N}/Plan-de-Pruebas-{project}-Sprint-{N}-{module}.md`.\n' +
       '>\n' +
@@ -346,6 +484,209 @@ if (!fs.existsSync(testCasesReadme)) {
   console.log(`  [created] 03-test-cases/README.md`);
 }
 
+// ---------------------------------------------------------------------------
+// 7. Ensure 06-defects/disputed/ exists (added in v1.11.0)
+//    Safe: only creates if missing. Never touches existing files.
+// ---------------------------------------------------------------------------
+const defectsDir   = path.join(qaRoot, '06-defects');
+const disputedDir  = path.join(defectsDir, 'disputed');
+const disputedReadme = path.join(disputedDir, 'README.md');
+
+if (fs.existsSync(defectsDir) && !fs.existsSync(disputedDir)) {
+  if (!dryRun) {
+    fs.mkdirSync(disputedDir, { recursive: true });
+    fs.writeFileSync(disputedReadme,
+`# 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).
+`, 'utf8');
+  }
+  updated.push(disputedDir);
+  console.log(`  [created] 06-defects/disputed/`);
+  console.log(`  [created] 06-defects/disputed/README.md`);
+} else if (!fs.existsSync(disputedReadme) && fs.existsSync(disputedDir)) {
+  if (!dryRun) {
+    fs.writeFileSync(disputedReadme,
+`# 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).
+`, 'utf8');
+  }
+  updated.push(disputedReadme);
+  console.log(`  [created] 06-defects/disputed/README.md`);
+}
+
+// ---------------------------------------------------------------------------
+// 8. Seed qa/memory/ template files if missing (added in v1.11.0)
+//    Safe: only creates files that do not exist. Never overwrites user content.
+// ---------------------------------------------------------------------------
+const memoryDir = path.join(qaRoot, 'memory');
+if (fs.existsSync(memoryDir)) {
+  const memorySrc = path.resolve(__dirname, '..', 'templates', 'memory');
+  for (const file of ['ci-pipeline-findings.md', 'e2e-stabilization-patterns.md', 'data-volatility-strategies.md']) {
+    const dest = path.join(memoryDir, file);
+    if (!fs.existsSync(dest)) {
+      if (!dryRun) {
+        fs.copyFileSync(path.join(memorySrc, file), dest);
+      }
+      updated.push(dest);
+      console.log(`  [created] memory/${file}`);
+    } else {
+      skipped.push(dest);
+    }
+  }
+}
+
+
+// ---------------------------------------------------------------------------
+// 9. Migration v1.11.x -> v1.12.0: lane-aware automation scaffold
+//
+//    v1.12.0 rewrote the automation scaffold around a lane table: playwright.config.ts
+//    and global-setup.ts now require() three CommonJS helpers under e2e/scripts/.
+//    init.js installs those for NEW projects only, so existing installations never
+//    receive them. This section carries them across.
+//
+//    Classification per file (the governing rule is: never break working user code):
+//
+//      a) Lane scripts (scripts/lane-config.js, lane-lock.js, global-setup-guards.js)
+//         plus playwright.config.ts and global-setup.ts form ONE ATOMIC GROUP,
+//         because config/global-setup require() the scripts by path. Installing a
+//         subset yields a project where Playwright cannot start at all. The group is
+//         installed only when EVERY member is either absent or provably pristine;
+//         otherwise the whole group is skipped with a warning and the rest of the
+//         upgrade continues. This is a coherent skip, not an abort: the project keeps
+//         the working setup it already had, so it is never left half-migrated.
+//
+//      b) fixtures/{auth,base,test-helpers}.ts are per-file. They are leaf modules -
+//         nothing in the scaffold require()s them by path - so a mixed state is
+//         still coherent.
+//
+//      c) .env.example is a reference template, never live config (the real file is
+//         .env, which this migration never touches). Overwritten when pristine.
+//
+//    "Pristine" means the file's normalised sha256 matches a hash this framework
+//    actually shipped in some earlier release (SHIPPED_SCAFFOLD_HASHES). Anything
+//    else is user-owned and is only ever warned about. The project's recorded
+//    frameworkVersion is deliberately NOT used: live installations report values
+//    like 1.1.3 and 1.0.0 that do not correspond to any real scaffold release.
+//
+//    Files that stay user-owned are additionally scanned for the trace-safety
+//    defect (.fill(password) leaks the password into Playwright traces). That is
+//    reported with file and line only - never patched, because the surrounding
+//    shapes differ per project (passwordSelector vs PASSWORD_SEL) and a bad regex
+//    edit to a working login is exactly the breakage this section must avoid.
+// ---------------------------------------------------------------------------
+const AUTOMATION_LANE_SCRIPTS = ['lane-config.js', 'lane-lock.js', 'global-setup-guards.js'];
+const AUTOMATION_FIXTURES     = ['auth.ts', 'base.ts', 'test-helpers.ts'];
+
+// A bare e2e/ directory is not evidence of an automation setup: section 5 above
+// creates e2e/tests/{helpers/debug,seeds}/ unconditionally. Only migrate a project
+// that actually has a scaffold, i.e. one of the files this migration would replace.
+const hasAutomationScaffold = ['playwright.config.ts', 'global-setup.ts', 'package.json']
+  .some((f) => fs.existsSync(path.join(e2eDir, f)));
+
+if (hasAutomationScaffold) {
+  const scaffoldSrc = path.resolve(__dirname, '..', 'templates', 'automation-scaffold');
+
+  // --- (a) the atomic lane group -------------------------------------------
+  const groupMembers = [
+    ...AUTOMATION_LANE_SCRIPTS.map((f) => ({
+      rel: `scripts/${f}`,
+      src: path.join(scaffoldSrc, 'scripts', f),
+      dest: path.join(e2eDir, 'scripts', f),
+      key: `automation-scaffold/scripts/${f}`,
+    })),
+    ...['playwright.config.ts', 'global-setup.ts'].map((f) => ({
+      rel: f,
+      src: path.join(scaffoldSrc, f),
+      dest: path.join(e2eDir, f),
+      key: `automation-scaffold/${f}`,
+    })),
+  ];
+
+  const blockers = groupMembers.filter((m) => fs.existsSync(m.dest) && !isPristine(m.dest, m.key));
+
+  if (blockers.length === 0) {
+    for (const m of groupMembers) {
+      forceWrite(m.dest, fs.readFileSync(m.src, 'utf8'));
+      console.log(`  [updated]  e2e/${m.rel}`);
+    }
+  } else {
+    warnings.push(
+      `Lane-aware automation scaffold (v1.12.0) NOT installed - these files are user-owned:\n` +
+        blockers.map((m) => `      e2e/${m.rel}`).join('\n') +
+        `\n    playwright.config.ts and global-setup.ts require() e2e/scripts/*.js, so the\n` +
+        `    group is installed all-or-nothing. Your current setup is left working and\n` +
+        `    untouched. To adopt lanes, merge these by hand from:\n` +
+        `      node_modules/@keber/qa-framework/templates/automation-scaffold/`
+    );
+    for (const m of groupMembers) skipped.push(m.dest);
+  }
+
+  // --- (b) fixtures, per file ----------------------------------------------
+  for (const file of AUTOMATION_FIXTURES) {
+    const dest = path.join(e2eDir, 'fixtures', file);
+    const key  = `automation-scaffold/fixtures/${file}`;
+    if (!fs.existsSync(dest) || isPristine(dest, key)) {
+      forceWrite(dest, fs.readFileSync(path.join(scaffoldSrc, 'fixtures', file), 'utf8'));
+      console.log(`  [updated]  e2e/fixtures/${file}`);
+    } else {
+      skipped.push(dest);
+      warnings.push(
+        `e2e/fixtures/${file} is user-owned - kept as is (v1.12.0 version not applied).`
+      );
+    }
+  }
+
+  // --- (c) .env.example ------------------------------------------------------
+  upgradeReferenceEnvExample(
+    path.join(e2eDir, '.env.example'),
+    path.join(scaffoldSrc, '.env.example'),
+    'automation-scaffold/.env.example',
+    'e2e/.env.example'
+  );
+
+  // --- trace safety on everything left user-owned ---------------------------
+  reportTraceSafety(e2eDir);
+}
+
+// --- integration scaffold: no lane coupling, so purely per-file -------------
+// Same reasoning as above: require a real scaffold file, not just the folder.
+const hasIntegrationScaffold = ['playwright.config.ts', 'global-setup.ts', 'package.json']
+  .some((f) => fs.existsSync(path.join(integrationDir, f)));
+
+if (hasIntegrationScaffold) {
+  const integrationSrc = path.resolve(__dirname, '..', 'templates', 'integration-scaffold');
+  for (const file of ['playwright.config.ts', 'global-setup.ts']) {
+    const dest = path.join(integrationDir, file);
+    const key  = `integration-scaffold/${file}`;
+    if (!fs.existsSync(dest) || isPristine(dest, key)) {
+      forceWrite(dest, fs.readFileSync(path.join(integrationSrc, file), 'utf8'));
+      console.log(`  [updated]  integration/${file}`);
+    } else {
+      skipped.push(dest);
+      warnings.push(`integration/${file} is user-owned - kept as is (v1.12.0 version not applied).`);
+    }
+  }
+  upgradeReferenceEnvExample(
+    path.join(integrationDir, '.env.example'),
+    path.join(integrationSrc, '.env.example'),
+    'integration-scaffold/.env.example',
+    'integration/.env.example'
+  );
+  reportTraceSafety(integrationDir);
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------
@@ -356,7 +697,7 @@ if (updated.length) {
 }
 if (skipped.length) {
   console.log('\n  Skipped (already up to date):');
-  for (const f of skipped) console.log(`    — ${path.relative(cwd, f)}`);
+  for (const f of skipped) console.log(`    - ${path.relative(cwd, f)}`);
 }
 if (warnings.length) {
   console.log('\n  Warnings:');
@@ -396,3 +737,93 @@ function copyDirForce(srcDir, destDir) {
   }
 }
 
+
+// Normalised content hash: strips a UTF-8 BOM and CRLF so that a file which only
+// differs by line endings or a BOM (both of which tooling rewrites silently) is
+// still recognised as the framework's own output.
+function scaffoldHash(content) {
+  const normalised = content.replace(/^/, '').replace(/\r\n/g, '\n');
+  return require('crypto').createHash('sha256').update(normalised, 'utf8').digest('hex');
+}
+
+// A file is "pristine" when its content is byte-identical (after normalisation) to
+// something this framework actually shipped. A key with no recorded hashes - a file
+// introduced in the current release - can never be pristine, so an existing copy is
+// always treated as user-owned.
+function isPristine(filePath, key) {
+  let content;
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return false;
+  }
+  const hash = scaffoldHash(content);
+
+  // Already identical to what this release ships: nothing to do, and certainly not a
+  // user edit. Computed rather than tabulated so the table never goes stale on release.
+  try {
+    const current = path.resolve(__dirname, '..', 'templates', ...key.split('/'));
+    if (fs.existsSync(current) && scaffoldHash(fs.readFileSync(current, 'utf8')) === hash) return true;
+  } catch {
+    /* fall through to the historical table */
+  }
+
+  const known = SHIPPED_SCAFFOLD_HASHES[key];
+  return Boolean(known) && known.includes(hash);
+}
+
+// .env.example is a reference template, never live configuration - the real values
+// live in .env, which is never touched here. Overwrite it when pristine; when the
+// user has edited it, keep theirs and say so.
+function upgradeReferenceEnvExample(dest, src, key, label) {
+  if (!fs.existsSync(src)) return;
+  if (!fs.existsSync(dest) || isPristine(dest, key)) {
+    forceWrite(dest, fs.readFileSync(src, 'utf8'));
+    console.log(`  [updated]  ${label}`);
+  } else {
+    skipped.push(dest);
+    warnings.push(
+      `${label} is user-owned - kept as is. New v1.12.0 keys may be missing; compare against\n` +
+        `    node_modules/@keber/qa-framework/templates/${key}`
+    );
+  }
+}
+
+// Trace safety (see skills/qa-automation/references/patterns.md, "Pattern 7"):
+// page.locator(...).fill(password) records the password in the Playwright trace.
+// Report location only. The surrounding code differs per project, so an automated
+// rewrite of a working login is more dangerous than the finding itself.
+function reportTraceSafety(rootDir) {
+  const offenders = [];
+  const FILL_PASSWORD = /\.fill\(\s*(?:password|pwd|[A-Za-z_$]*(?:[Pp]ass(?:word)?|PASSWORD)[A-Za-z_$]*)\s*\)/;
+
+  (function walk(dir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry.name === 'node_modules' || entry.name.startsWith('.')) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walk(full);
+      } else if (/\.ts$/.test(entry.name)) {
+        const lines = fs.readFileSync(full, 'utf8').split(/\r?\n/);
+        lines.forEach((line, i) => {
+          if (FILL_PASSWORD.test(line)) offenders.push(`${path.relative(cwd, full)}:${i + 1}`);
+        });
+      }
+    }
+  })(rootDir);
+
+  if (offenders.length) {
+    warnings.push(
+      `Trace safety: the password is written with .fill(), which stores it in the\n` +
+        `    Playwright trace. Replace with the page.evaluate() form ("Pattern 7" in\n` +
+        `    .github/skills/qa-automation/references/patterns.md):\n` +
+        offenders.map((o) => `      ${o}`).join('\n')
+    );
+  }
+}