@keber/qa-framework 1.5.1 → 1.6.1

package/docs/folder-structure-guide.md

@@ -197,7 +197,7 @@ Most projects will have sparse content here — the 05-test-scenarios.md files i
 ```
 06-defects/
 ├── README.md
-├── active/
+├── open/
 │   └── DEF-{NNN}-{slug}.md
 └── resolved/
     └── DEF-{NNN}-{slug}.md
@@ -218,32 +218,36 @@ See `docs/generalization-decisions.md §7` for the full evaluation of this folde
 
 ```
 07-automation/
-├── README.md                       ← How to run, where reports go, worker config
-├── e2e/                            ← Playwright E2E tests
-│   ├── package.json
-│   ├── playwright.config.ts
-│   ├── global-setup.ts             ← Pre-suite login + storageState save
-│   ├── .env                        ← Local credentials (NEVER commit)
-│   ├── .env.example                ← Template (always commit)
-│   ├── .auth/                      ← storageState files (gitignored)
-│   ├── fixtures/
-│   │   ├── auth.ts                 ← loginAs(page, role) helper
-│   │   └── test-helpers.ts         ← EXEC_IDX, date helpers, etc.
-│   ├── page-objects/               ← Page Object Model classes
-│   ├── tests/
-│   │   ├── {module}/               ← Tests by module
-│   │   ├── helpers/debug/          ← Diagnostic scripts (not part of suite)
-│   │   └── seeds/                  ← Data seeding specs (excluded from runs)
-│   ├── diagnosis/                  ← Screenshots and debug output (gitignored)
-│   └── scripts/                    ← One-off utility scripts
-└── integration/                    ← API-level tests (if applicable)
+├── README.md                       <- How to run, where reports go, worker config
+├── e2e/                            <- Playwright E2E project (self-contained)
+│   ├── playwright.config.ts        <- Test runner config (installed by init)
+│   ├── package.json                <- Playwright dependencies (installed by init)
+│   ├── global-setup.ts             <- Pre-suite login + storageState save (installed by init)
+│   ├── .env                        <- Local credentials (NEVER commit)
+│   ├── .env.example                <- Template (always commit, installed by init)
+│   ├── .auth/                      <- storageState files (gitignored)
+│   ├── fixtures/                   <- Installed by init
+│   │   ├── auth.ts             <- loginAs(page, role) helper
+│   │   └── test-helpers.ts     <- EXEC_IDX, date helpers, etc.
+│   ├── page-objects/               <- Page Object Model classes (project-maintained)
+│   ├── tests/                      <- Spec files, organized by module
+│   │   ├── {module}/           <- Stub .spec.ts files generated by init per submodule
+│   │   ├── helpers/debug/      <- Diagnostic scripts (not part of suite)
+│   │   └── seeds/              <- Data seeding specs (excluded from runs)
+│   └── diagnosis/                  <- Screenshots and debug output (gitignored)
+├── integration/                    <- API-level tests (k6, JMeter, Azure Load Testing)
+│   └── README.md                   <- Integration test setup and run instructions
+└── load/                           <- Load / performance tests (future)
+    └── README.md                   <- Load test setup and run instructions
 ```
 
 **Important rules**:
-- Always run Playwright from the **repo root**, not from inside `qa/07-automation/e2e/`
+- Run Playwright from `qa/07-automation/e2e/` (where `playwright.config.ts` lives): `cd qa/07-automation/e2e && npx playwright test`
 - Seeds are excluded from normal test runs via `testIgnore` in `playwright.config.ts`
-- Debug artifacts go into `diagnosis/` — never into the repo root
-- `.auth/` is always gitignored
+- Debug artifacts go into `e2e/diagnosis/` -- never into the repo root
+- `.auth/` and `.env` are always gitignored
+- Files installed by `init` must not be deleted -- they are the project's automation bootstrap
+- `integration/` and `load/` are independent projects with their own toolchains (k6, JMeter, etc.) -- they do not depend on `e2e/`
 
 ---
 

package/docs/installation.md

@@ -16,56 +16,48 @@
 ## Option A — npm install (recommended)
 
 ```bash
-# Install as a dev dependency
-npm install --save-dev keber/qa-framework
-
-# Run the init command
-npx qa-framework init
+npm install --save-dev @keber/qa-framework
 ```
 
-The `init` command will prompt you for:
+The `postinstall` script runs `init --skip-if-exists` automatically. On first install it
+creates the full `qa/` structure without prompts, reading `qa-framework.config.json` if
+present or bootstrapping defaults.
 
-1. **Project name** (used in config and directory labels)
-2. **QA base URL** (e.g., `https://myproject-qa.example.com`)
-3. **Login path** (e.g., `/login` or `/Seguridad/Login`)
-4. **Number of test user roles** (1 = single role, 2+ = multi-role)
-5. **Enable Playwright integration?** (y/n)
-6. **Enable Azure DevOps integration?** (y/n)
+After install, read `qa/AGENT-NEXT-STEPS.md` for the exact follow-up steps.
 
-After answering these, `init` creates:
+`init` creates:
 
 ```
 qa/
-├── README.md                       ← Prefilled with your project name
-├── QA-STRUCTURE-GUIDE.md           ← Full structure guide
-├── qa-framework.config.json        ← Your project config
-├── 00-guides/                      ← Agent instructions (copied)
-├── 00-standards/                   ← Templates and naming conventions
-├── 01-specifications/README.md
-├── 02-test-plans/README.md
-├── 03-test-cases/README.md
-├── 04-test-data/README.md
-├── 05-test-execution/README.md
-├── 06-defects/README.md
-├── 07-automation/README.md
-└── 08-azure-integration/README.md  ← Only if ADO enabled
-```
-
-If Playwright is enabled, it also creates:
-
-```
-qa/07-automation/e2e/
-├── package.json
-├── playwright.config.ts
-├── global-setup.ts
-├── .env.example
-└── fixtures/
-    └── auth.ts
+├── README.md                       <- Prefilled with your project name
+├── AGENT-NEXT-STEPS.md             <- Follow-up checklist for the agent
+├── QA-STRUCTURE-GUIDE.md           <- Full structure guide (framework-owned)
+├── qa-framework.config.json        <- Your project config
+├── 00-standards/                   <- Templates and naming conventions
+├── 01-specifications/
+├── 02-test-plans/
+├── 03-test-cases/
+├── 04-test-data/
+├── 05-test-execution/
+├── 06-defects/open|resolved/
+├── 07-automation/
+│   ├── e2e/                        <- Playwright project (self-contained)
+│   │   ├── playwright.config.ts
+│   │   ├── global-setup.ts
+│   │   ├── .env.example
+│   │   └── fixtures/auth.ts + test-helpers.ts
+│   ├── integration/README.md       <- Placeholder for k6, JMeter, etc.
+│   └── load/README.md              <- Placeholder for load tests
+└── 08-azure-integration/README.md
+└── memory/INDEX.md
+
+.github/copilot-instructions.md     <- Generated agent rules
+.github/skills/                     <- 8 agent skill sets (SKILL.md + references/)
 ```
 
 ---
 
-## Option B — Clone or copy (early adoption / no npm registry)
+## Option B — Clone or copy (no npm registry)
 
 ```bash
 # From your project root
@@ -82,15 +74,33 @@ node tools/qa-framework/scripts/cli.js init
 If you prefer to control exactly what gets created:
 
 ```bash
-# Clone the package
 git clone https://github.com/your-org/qa-framework.git tools/qa-framework
 
-# Copy only the templates you need
+# Copy templates
 cp -r tools/qa-framework/templates/specification qa/01-specifications/shared/
-cp -r tools/qa-framework/agent-instructions qa/00-guides/
 cp -r tools/qa-framework/templates/automation-scaffold qa/07-automation/e2e/
 
-# Then manually fill in qa-framework.config.json
+# Then fill in qa-framework.config.json manually
+```
+
+---
+
+## Upgrading
+
+After `npm update @keber/qa-framework`:
+
+```bash
+npx qa-framework upgrade
+```
+
+This overwrites only framework-owned files (`.github/skills/`, `copilot-instructions.md`,
+`QA-STRUCTURE-GUIDE.md`) and migrates the `07-automation/` structure if upgrading from
+v1.5.x. Your specs, tests, and memory are never touched.
+
+Use `--dry-run` to preview without writing:
+
+```bash
+npx qa-framework upgrade --dry-run
 ```
 
 ---

package/docs/usage-with-agent.md

@@ -20,16 +20,13 @@ This framework is designed so that an IDE agent (such as GitHub Copilot in VS Co
 
 ```
 # Install the framework
-"Run the qa-framework init command for this project"
+"Run npm install @keber/qa-framework for this project"
 
-# Read the framework instructions
-"Read the file qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md"
-
-# Generate the QA structure
-"Generate the full qa/ directory structure using the framework config"
+# Let the agent self-configure
+"Read qa/AGENT-NEXT-STEPS.md and complete the setup steps"
 
 # Analyze a module
-"Analyze the module at [URL/route] following qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md"
+"Analyze the module at [URL/route] using the qa-module-analysis skill"
 
 # Generate spec, plan, cases, and automation
 "For submodule {name}, generate all 6 spec files following the templates in qa/00-standards/"
@@ -37,53 +34,44 @@ This framework is designed so that an IDE agent (such as GitHub Copilot in VS Co
 "Write Playwright E2E tests for TC-{ID} through TC-{ID}"
 
 # Integrate results with Azure DevOps
-"Follow qa/08-azure-integration/AGENT-ADO-INTEGRATION.md to sync results with ADO"
+"Load the qa-ado-integration skill and sync results with ADO"
 
 # Maintenance
-"Module {name} was updated. Review and update the spec files following qa/00-guides/AGENT-INSTRUCTIONS-MAINTENANCE.md"
+"Module {name} was updated. Load the qa-maintenance skill and update the affected artifacts"
 ```
 
 ---
 
 ## Setting Up Agent Instructions in VS Code
 
-### Option A — Reference files in the agent conversation
-
-Simply paste the relevant instruction file path into the Copilot chat:
-
-```
-Read qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md and then analyze the module at {URL}
-```
-
-### Option B — Workspace instructions file (recommended)
+### Option A — Workspace instructions file (recommended)
 
-Create `.github/copilot-instructions.md` in your project root:
+`init` generates `.github/copilot-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.
 
-```markdown
-# QA Framework Instructions
+To regenerate after an upgrade:
 
-This project uses qa-framework v1.0.0 for spec-driven automated testing.
-
-## Agent behavior rules
+```bash
+npx qa-framework upgrade
+```
 
-1. Before performing any QA task, read the relevant instruction file from `qa/00-guides/`
-2. Always save artifacts in the correct `qa/` subfolder per `qa/QA-STRUCTURE-GUIDE.md`
-3. Never hardcode credentials — always use env vars and `<PLACEHOLDER>` in documentation
-4. follow the naming conventions in `qa/00-standards/naming-conventions.md`
+### Option B — Reference skills directly in the agent conversation
 
-## Available instructions
+Paste a skill path into the Copilot chat:
 
-- Module analysis: `qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md`
-- Spec generation: `qa/00-guides/AGENT-INSTRUCTIONS-SPEC-GENERATION.md`
-- Test cases: `qa/00-guides/AGENT-INSTRUCTIONS-TEST-CASES.md`
-- Automation: `qa/00-guides/AGENT-INSTRUCTIONS-AUTOMATION.md`
-- ADO integration: `qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md`
+```
+Read .github/skills/qa-module-analysis/SKILL.md and analyze the module at {URL}
 ```
 
 ### Option C — Individual task prompts
 
-For each major QA task, use the prompt from the relevant `agent-instructions/*.md` file
-as the starting prompt. These are designed to be copied and pasted directly.
+For each major QA task, ask the agent to load the relevant skill:
+
+```
+Load the qa-automation skill (.github/skills/qa-automation/SKILL.md) and implement
+tests for the submodule {name}
+```
 
 ---
 
@@ -92,11 +80,11 @@ as the starting prompt. These are designed to be copied and pasted directly.
 ### Session 1: Initial Module Analysis
 
 ```
-1. Agent reads qa/00-guides/AGENT-INSTRUCTIONS-MODULE-ANALYSIS.md
-2. Agent navigates to QA_BASE_URL using Playwright CLI
-3. Agent explores the module: screenshots, routes, form fields, APIs
-4. Agent produces qa/01-specifications/module-{name}/submodule-{x}/ (6 files each)
-5. Agent writes SESSION-SUMMARY-{date}.md at qa/ root
+1. Agent reads qa/AGENT-NEXT-STEPS.md (auto, on conversation start)
+2. Agent loads .github/skills/qa-module-analysis/SKILL.md
+3. Agent navigates to QA_BASE_URL using browser automation
+4. Agent explores the module: screenshots, routes, form fields, APIs
+5. Agent produces qa/01-specifications/module-{name}/submodule-{x}/ (6 files each)
 6. Human reviews specs and approves before proceeding
 ```
 
@@ -104,7 +92,7 @@ as the starting prompt. These are designed to be copied and pasted directly.
 
 ```
 1. Agent reads approved specs from 01-specifications/
-2. Agent reads qa/00-guides/AGENT-INSTRUCTIONS-TEST-CASES.md
+2. Agent loads .github/skills/qa-test-plan/SKILL.md
 3. Agent selects TCs for automation (P0/P1) and manual (P2/P3)
 4. Agent writes qa/02-test-plans/{module}-automated-test-plan.md
 5. Human reviews priorities
@@ -114,9 +102,9 @@ as the starting prompt. These are designed to be copied and pasted directly.
 
 ```
 1. Agent reads approved test plan
-2. Agent reads qa/00-guides/AGENT-INSTRUCTIONS-AUTOMATION.md
+2. Agent loads .github/skills/qa-automation/SKILL.md
 3. Agent writes Playwright spec files in qa/07-automation/e2e/tests/{module}/
-4. Agent runs tests, iterates until stable
+4. Agent runs tests from qa/07-automation/e2e/ (cd e2e && npx playwright test)
 5. Agent writes qa/05-test-execution/automated/{date}.md
 6. Human reviews automation coverage
 ```
@@ -124,7 +112,7 @@ as the starting prompt. These are designed to be copied and pasted directly.
 ### Session 4: ADO Sync (if enabled)
 
 ```
-1. Agent reads qa/08-azure-integration/AGENT-ADO-INTEGRATION.md
+1. Agent loads .github/skills/qa-ado-integration/SKILL.md
 2. Agent runs inject-ado-ids.ps1 to prefix test titles
 3. Agent verifies runner output appears in ADO Test Plan
 4. Agent updates qa/08-azure-integration/ado-ids-mapping-{project}.json
@@ -136,23 +124,23 @@ as the starting prompt. These are designed to be copied and pasted directly.
 
 ### DO
 
-- ✅ Read the instruction file before starting any QA task
-- ✅ Save all artifacts in the exact path specified by the structure guide
-- ✅ Use TC-ID, RN-ID, FL-ID naming consistently
-- ✅ Replace credentials with `<PLACEHOLDER>` in any markdown output
-- ✅ Write a brief session summary after each working session
-- ✅ Reference the DEF-ID or ADO WI ID in every `test.skip()` call
-- ✅ Validate test stability with ≥2 passes using different `EXEC_IDX` values
+- Read `qa/AGENT-NEXT-STEPS.md` at the start of each conversation (auto-enforced by copilot-instructions.md)
+- 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
+- Replace credentials with `<PLACEHOLDER>` in any markdown output
+- Reference the DEF-ID or ADO WI ID in every `test.skip()` call
+- Validate test stability with >= 2 passes using different `EXEC_IDX` values
+- Run Playwright from `qa/07-automation/e2e/` (`cd qa/07-automation/e2e && npx playwright test`)
 
 ### DON'T
 
-- ❌ Invent test cases without first observing the QA environment
-- ❌ Hardcode credentials, DNIs, or personal data in any file
-- ❌ Save screenshots or debug output to the project root
-- ❌ Run Playwright directly from inside `qa/07-automation/e2e/` (always from project root)
-- ❌ Modify files in `00-guides/` or `00-standards/` (those are framework-owned)
-- ❌ Create test cases for features marked `BLOCKED-PERMISSIONS` without noting the blocker
-- ❌ Remove a `test.skip()` without verifying the underlying defect is resolved
+- Invent test cases without first observing the QA environment
+- Hardcode credentials, DNIs, or personal data in any file
+- Save screenshots or debug output to the project root
+- Modify files in `00-standards/` (those are project-customized after install)
+- Create test cases for features marked `BLOCKED-PERMISSIONS` without noting the blocker
+- Remove a `test.skip()` without verifying the underlying defect is resolved
 
 ---
 
@@ -182,21 +170,21 @@ npx qa-framework validate
 ```
 
 This performs:
-- Structure check (all 9 folders exist)
+- Structure check (all required folders exist)
 - Config check (required fields populated)
 - Credential scan (no hardcoded passwords in markdown)
-- Naming check (IC IDs follow `TC-{MODULE}-{NNN}` pattern)
+- Naming check (TC IDs follow `TC-{MODULE}-{SUBMODULE}-{NNN}` pattern)
 - Coverage check (all spec TCs have matching test file references)
 
 ---
 
 ## Continuing from a Previous Session
 
-Ask the agent:
+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:
 
 ```
-"Read qa/SESSION-SUMMARY-{last-date}.md and qa/README.md, then tell me where we left off 
-and what the next steps are."
+"Read qa/README.md and qa/memory/INDEX.md, then tell me where we left off."
 ```
 
 The session summary + README combination gives the agent sufficient context to resume

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

@@ -31,7 +31,7 @@ variables:
   - name: NODE_VERSION
     value: '20.x'
   - name: QA_DIR
-    value: 'qa/07-automation'
+    value: 'qa/07-automation/e2e'
   - name: ADO_SYNC_DISABLED
     value: 'false'
 

package/integrations/playwright/README.md

@@ -17,7 +17,7 @@ Peer dependency: `@playwright/test >= 1.40.0`
 ## Configuration
 
 Copy `templates/automation-scaffold/playwright.config.ts` into your project's
-`qa/07-automation/` directory and replace all `{{PLACEHOLDER}}` values.
+`qa/07-automation/e2e/` directory and replace all `{{PLACEHOLDER}}` values.
 
 ## Key conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keber/qa-framework",
-  "version": "1.5.1",
+  "version": "1.6.1",
   "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",

package/scripts/init.js

@@ -85,7 +85,7 @@ const topLevelFolders = [
   '05-test-execution',
   '06-defects/open',
   '06-defects/resolved',
-  '07-automation/e2e',
+  '07-automation/e2e/tests',
   '08-azure-integration',
   'memory',
 ];
@@ -185,8 +185,8 @@ for (const mod of modules) {
       }
     }
 
-    // Create automation e2e subdir placeholder
-    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', moduleKey);
+    // Create automation spec stub in e2e/tests/{module}/
+    const e2eDir = path.join(qaRoot, '07-automation', 'e2e', 'tests', moduleKey);
     fs.mkdirSync(e2eDir, { recursive: true });
     const specTs = path.join(e2eDir, `${subKey}.spec.ts`);
     if (!fs.existsSync(specTs)) {
@@ -196,26 +196,34 @@ for (const mod of modules) {
   }
 }
 
-// --- Automation scaffold ---
-const automationDir = path.join(qaRoot, '07-automation');
-const scaffoldSrc   = path.resolve(__dirname, '..', 'templates', 'automation-scaffold');
+// --- Automation scaffold (lives in 07-automation/e2e/) ---
+const automationDir  = path.join(qaRoot, '07-automation');
+const e2eScaffoldDir = path.join(automationDir, 'e2e');
+const scaffoldSrc    = path.resolve(__dirname, '..', 'templates', 'automation-scaffold');
+fs.mkdirSync(e2eScaffoldDir, { recursive: true });
 for (const file of ['playwright.config.ts', 'global-setup.ts', '.env.example', 'package.json']) {
-  const dest = path.join(automationDir, file);
+  const dest = path.join(e2eScaffoldDir, file);
   if (!fs.existsSync(dest)) {
     fs.copyFileSync(path.join(scaffoldSrc, file), dest);
     console.log(`  [created] ${path.relative(cwd, dest)}`);
   }
 }
-const fixturesDir = path.join(automationDir, 'fixtures');
+const fixturesDir = path.join(e2eScaffoldDir, 'fixtures');
 fs.mkdirSync(fixturesDir, { recursive: true });
 for (const file of ['auth.ts', 'test-helpers.ts']) {
   const dest = path.join(fixturesDir, file);
   if (!fs.existsSync(dest)) {
     fs.copyFileSync(path.join(scaffoldSrc, 'fixtures', file), dest);
-    console.log(`  [created] ${path.relative(cwd  , dest)}`);
+    console.log(`  [created] ${path.relative(cwd, dest)}`);
   }
 }
 
+// --- 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`);
+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`);
+
 // --- ADO integration placeholder ---
 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`);
@@ -344,12 +352,12 @@ npm install @keber/ado-qa
 **Playwright automation:**
 \`\`\`bash
 npm install @playwright/test
-cd qa/07-automation && npm install && npx playwright install chromium
+cd qa/07-automation/e2e && npm install && npx playwright install chromium
 \`\`\`
 
 ### 3. Credentials
-- Copy \`qa/07-automation/.env.example\` → \`qa/07-automation/.env\` and fill in credentials
-- Add \`qa/07-automation/.env\` and \`qa/07-automation/.auth/\` to \`.gitignore\`
+- 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\`
 `;
 const nextStepsPath = path.join(qaRoot, 'AGENT-NEXT-STEPS.md');
 fs.writeFileSync(nextStepsPath, nextStepsContent, 'utf8');

package/scripts/upgrade.js

@@ -8,21 +8,30 @@
  *
  * What this command does (safe by design):
  *   ALWAYS updates (framework-owned):
- *     - .github/skills/             ← New skills architecture; always current
- *     - .github/copilot-instructions.md ← Pipeline sequencer; framework-owned
- *     - qa/QA-STRUCTURE-GUIDE.md    ← Folder reference; framework-owned
+ *     - .github/skills/             <- New skills architecture; always current
+ *     - .github/copilot-instructions.md <- Pipeline sequencer; framework-owned
+ *     - qa/QA-STRUCTURE-GUIDE.md    <- Folder reference; framework-owned
+ *
+ *   MIGRATES (v1.5.x -> v1.6.0, non-destructive):
+ *     - qa/07-automation/playwright.config.ts  -> qa/07-automation/e2e/
+ *     - qa/07-automation/global-setup.ts       -> qa/07-automation/e2e/
+ *     - qa/07-automation/package.json          -> qa/07-automation/e2e/
+ *     - qa/07-automation/.env.example          -> qa/07-automation/e2e/
+ *     - qa/07-automation/fixtures/             -> qa/07-automation/e2e/fixtures/
+ *     - qa/07-automation/e2e/{module}/         -> qa/07-automation/e2e/tests/{module}/
+ *     - Creates integration/ and load/ placeholders
  *
  *   NEVER touches (project-owned):
- *     - qa/01-specifications/       ← Your specs
- *     - qa/02-test-plans/           ← Your test plans
- *     - qa/03-test-cases/           ← Your TCs
- *     - qa/07-automation/           ← Your Playwright code
- *     - qa/memory/                  ← Your learnings
- *     - qa/README.md                ← Your living index
- *     - qa/AGENT-NEXT-STEPS.md       ← Your sprint queue
+ *     - qa/01-specifications/       <- Your specs
+ *     - qa/02-test-plans/           <- Your test plans
+ *     - qa/03-test-cases/           <- Your TCs
+ *     - qa/07-automation/e2e/tests/ <- Your Playwright tests (only moves, never overwrites)
+ *     - qa/memory/                  <- Your learnings
+ *     - qa/README.md                <- Your living index
+ *     - qa/AGENT-NEXT-STEPS.md      <- Your sprint queue
  *
  *   REPORTS but does not delete:
- *     - qa/00-guides/               ← Old location (can be deleted manually)
+ *     - qa/00-guides/               <- Old location (can be deleted manually)
  */
 
 'use strict';
@@ -98,6 +107,86 @@ if (fs.existsSync(oldGuidesDir)) {
   );
 }
 
+// ---------------------------------------------------------------------------
+// 5. Migration v1.5.x -> v1.6.0: restructure qa/07-automation/
+//    Safe: only moves files when source exists and destination does NOT.
+// ---------------------------------------------------------------------------
+const automationDir  = path.join(qaRoot, '07-automation');
+const e2eDir         = path.join(automationDir, 'e2e');
+
+// 5a. Scaffold files: 07-automation/*.* -> 07-automation/e2e/*.*
+const scaffoldFiles = ['playwright.config.ts', 'global-setup.ts', 'package.json', '.env.example', 'package-lock.json'];
+for (const file of scaffoldFiles) {
+  const oldPath = path.join(automationDir, file);
+  const newPath = path.join(e2eDir, file);
+  if (fs.existsSync(oldPath) && !fs.existsSync(newPath)) {
+    if (!dryRun) {
+      fs.mkdirSync(e2eDir, { recursive: true });
+      fs.renameSync(oldPath, newPath);
+    }
+    updated.push(newPath);
+    console.log(`  [migrated] ${path.relative(cwd, oldPath)} -> e2e/${file}`);
+  }
+}
+
+// 5b. fixtures/: 07-automation/fixtures/ -> 07-automation/e2e/fixtures/
+const oldFixturesDir = path.join(automationDir, 'fixtures');
+const newFixturesDir = path.join(e2eDir, 'fixtures');
+if (fs.existsSync(oldFixturesDir) && !fs.existsSync(newFixturesDir)) {
+  if (!dryRun) {
+    fs.mkdirSync(e2eDir, { recursive: true });
+    fs.renameSync(oldFixturesDir, newFixturesDir);
+  }
+  updated.push(newFixturesDir);
+  console.log(`  [migrated] ${path.relative(cwd, oldFixturesDir)}/ -> e2e/fixtures/`);
+}
+
+// 5c. Spec stubs: e2e/{module}/*.spec.ts -> e2e/tests/{module}/
+//     Moves any directory directly under e2e/ that is not a known non-module dir.
+const testsDir = path.join(e2eDir, 'tests');
+const knownE2eDirs = new Set(['tests', 'page-objects', 'fixtures', 'diagnosis', 'scripts', 'seeds', 'helpers']);
+if (fs.existsSync(e2eDir)) {
+  for (const entry of fs.readdirSync(e2eDir, { withFileTypes: true })) {
+    if (!entry.isDirectory() || knownE2eDirs.has(entry.name)) continue;
+    const oldModDir = path.join(e2eDir, entry.name);
+    const newModDir = path.join(testsDir, entry.name);
+    if (!fs.existsSync(newModDir)) {
+      if (!dryRun) {
+        fs.mkdirSync(testsDir, { recursive: true });
+        fs.renameSync(oldModDir, newModDir);
+      }
+      updated.push(newModDir);
+      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.`
+      );
+    }
+  }
+}
+
+// 5d. Create integration/ and load/ placeholders if missing.
+const integrationReadme = path.join(automationDir, 'integration', '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');
+  }
+  updated.push(integrationReadme);
+  console.log(`  [created] ${path.relative(cwd, integrationReadme)}`);
+}
+if (!fs.existsSync(loadReadme)) {
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(loadReadme), { recursive: true });
+    fs.writeFileSync(loadReadme,
+      '# Load Tests\n\n> Placeholder for load and performance tests.\n> Each tool gets its own subdirectory (e.g. k6/, jmeter/).\n', 'utf8');
+  }
+  updated.push(loadReadme);
+  console.log(`  [created] ${path.relative(cwd, loadReadme)}`);
+}
+
 // ---------------------------------------------------------------------------
 // Summary
 // ---------------------------------------------------------------------------