@keber/qa-framework 1.7.0 → 1.7.1

package/CHANGELOG.md

@@ -33,6 +33,18 @@ has been removed or parameterized. See `docs/comparison-matrix.md` and `docs/gen
 
 ---
 
+## [1.7.1] - 2026-05-06
+
+### Fixed
+
+- **Agent instructions template extracted** — `templates/qa-framework.instructions.md` is now
+  the single source of truth for QA agent rules. Both `init` and `upgrade` read and interpolate
+  this file instead of maintaining separate hardcoded strings, eliminating the rule divergence
+  that caused `upgrade` to deploy only 7 rules instead of 11.
+- `upgrade.js` — removed `buildCopilotInstructions()` function (dead code after template extraction).
+
+---
+
 ## [1.7.0] - 2026-05-06
 
 ### Changed

package/README.md

@@ -1,7 +1,7 @@
 # qa-framework
 
 > Reusable, installable, agent-oriented QA framework for spec-driven automated testing.
-> Current version: **v1.7.0**
+> Current version: **v1.7.1**
 
 ---
 

package/package.json

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

@@ -264,17 +264,16 @@ const adoSkillReady  = fs.existsSync(path.join(cwd, '.github', 'skills', 'ado-qa
 const adoAvailable   = adoQaInstalled || adoSkillReady;
 
 const adoSection = adoAvailable
-  ? `
-## Azure DevOps integration (ado-qa)
+  ? `## 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)
+  : `## 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:
@@ -282,53 +281,13 @@ Refer to \`qa/00-guides/AGENT-INSTRUCTIONS-ADO-INTEGRATION.md\` for the full ADO
 > npm install github:keber/ado-qa
 > \`\`\`
 > This will automatically copy the ADO skills to \`.github/skills/\` via postinstall.
-`;
 
-const copilotInstrContent = `---
-applyTo: '**'
----
-# QA Framework Instructions
-
-This project uses \`@keber/qa-framework\` v${config.frameworkVersion ?? '1.0.0'} for spec-driven automated testing.
-
-## Agent behavior rules
-
-0. **On every conversation start:** check if \`qa/AGENT-NEXT-STEPS.md\` exists. If it does, read it and complete its steps before anything else.
-1. Before performing any QA task, load the relevant skill from \`.github/skills/\`. For project context, read \`qa/memory/INDEX.md\` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
-2. Always save artifacts in the correct \`qa/\` subfolder - refer to \`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\`
-5. Read previous test suites code in \`qa/07-automation/e2e/tests/\` if available before writing new automation to maintain consistency in style and approach
-6. Project QA config is at \`qa/qa-framework.config.json\`
-7. Save learnings in \`qa/memory/\` with proper naming and metadata. Always update \`qa/memory/INDEX.md\` after adding or updating any memory file.
-8. **Sprint/module completion criteria:** A sprint or module is complete when every TC in scope has one of these three valid states - and no other: (a) \`test()\` passing: the app meets the spec; (b) \`test.fail()\`: the app violates the spec **and** a file \`qa/06-defects/open/DEF-SIS-NNN_*.md\` exists documenting which business rule is violated and what the app actually does; (c) \`test.skip()\`: the TC is not yet executable, annotated with \`PENDING-CODE\` and a linked issue. A sprint is **not** complete if any TC is failing without \`test.fail()\`, or has \`test.fail()\` without a defect file, or has \`test.skip()\` without a \`PENDING-CODE\` reason.
-9. **On sprint/module completion:** (1) update the module status row in \`qa/README.md\`; (2) move the completed sprint checklist from \`AGENT-NEXT-STEPS.md\` to the \`## Sprint History\` section of \`qa/README.md\`; (3) trim \`AGENT-NEXT-STEPS.md\` so it contains only the next sprint — never let it accumulate more than one active sprint.
-10. **Assertion polarity rule (BLOCKING):** A test must assert what the **spec** requires, not what the app currently does. If the app fails to meet the spec, use \`test.fail()\` + correct assertion to document the defect — **never invert or weaken an assertion to make a test go green.** A failing test that exposes a real defect is always more valuable than a passing test that hides one.
-11. **Character encoding safety (BLOCKING):** In ALL generated content (markdown, scripts, test titles, ADO fields, config files), never use characters at these Unicode code points: em-dash (U+2014), en-dash (U+2013), horizontal ellipsis (U+2026), smart/curly quotes (U+201C, U+201D, U+2018, U+2019), or directional arrows (U+2190-U+21FF). Use ASCII equivalents instead: \` - \` (hyphen with surrounding spaces) for dashes, \`...\` for ellipsis, \`"\` and \`'\` for quotes, \`->\` and \`<-\` for arrows. Exception: Latin Extended characters (U+00C0-U+024F) are always permitted - this covers Spanish vowels with accents (U+00E0-U+00FA), n with tilde (U+00F1/U+00D1), and u/o with umlaut (U+00FC/U+00DC, U+00F6/U+00D6).
-
-## Formatting rules for generated content
-1. Generate the output in \`UTF-8\` encoding without BOM (\`UTF-8\`, no signature).
-2. Ensure the raw output is \`UTF-8\` encoded with no \`EF BB BF\` bytes at the beginning.
-
-## QA Pipeline
-
-Stages must run in order. Never start a stage unless its prerequisite is met.
-
-| Stage | Task | Skill | Prerequisite |
-|---|---|---|---|
-| 1 | Analyze module | \`.github/skills/qa-module-analysis/SKILL.md\` | None |
-| 2 | Generate specifications | \`.github/skills/qa-spec-generation/SKILL.md\` | 00-inventory.md exists |
-| 3 | Generate test plan | \`.github/skills/qa-test-plan/SKILL.md\` | 05-test-scenarios.md exists |
-| 4 | Generate test cases | \`.github/skills/qa-test-cases/SKILL.md\` | Test plan exists |
-| 5 | Generate automation | \`.github/skills/qa-automation/SKILL.md\` | Specs approved, no PENDING-CODE |
-| 5b | Stabilize failing tests | \`.github/skills/qa-test-stabilization/SKILL.md\` | Failing tests exist |
-| 6 | Maintenance | \`.github/skills/qa-maintenance/SKILL.md\` | Application change delivered |
-| — | ADO integration | \`.github/skills/qa-ado-integration/SKILL.md\` | ADO enabled in config |
-
-## Project KB
-1. \`qa/README.md\`          — The Living Index: module status, sprint history, blockers, quick-start commands.
-2. \`qa/memory/INDEX.md\`    — Index of all memory files; load this before selecting which files to read.
 `;
+
+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);
 writeIfMissing(copilotInstrPath, copilotInstrContent);
 
 // --- AGENT-NEXT-STEPS.md — readable by the agent after install ---

package/scripts/upgrade.js

@@ -84,7 +84,10 @@ if (!fs.existsSync(skillsSrc)) {
 // 2. .github/instructions/qa-framework.instructions.md — overwrite (framework-owned)
 // ---------------------------------------------------------------------------
 const copilotInstrPath = path.join(githubDir, 'instructions', 'qa-framework.instructions.md');
-const copilotContent = buildCopilotInstructions(config);
+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}}', '');
 forceWrite(copilotInstrPath, copilotContent);
 
 // ---------------------------------------------------------------------------
@@ -312,43 +315,3 @@ function copyDirForce(srcDir, destDir) {
   }
 }
 
-function buildCopilotInstructions(cfg) {
-  const version = cfg.frameworkVersion ?? '1.0.0';
-  return `---
-applyTo: '**'
----
-# QA Framework Instructions
-
-This project uses \`@keber/qa-framework\` v${version} for spec-driven automated testing.
-
-## Agent behavior rules
-
-0. **On every conversation start:** check if \`qa/AGENT-NEXT-STEPS.md\` exists. If it does, read it and complete its steps before anything else.
-1. Before performing any QA task, load the relevant skill from \`.github/skills/\`. For project context, read \`qa/memory/INDEX.md\` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
-2. Always save artifacts in the correct \`qa/\` subfolder — refer to \`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\`
-5. Project QA config is at \`qa/qa-framework.config.json\`
-6. Save learnings in \`qa/memory/\` with proper naming and metadata. Always update \`qa/memory/INDEX.md\` after adding or updating any memory file.
-7. **On module/sprint completion** (all TCs passing): (1) update the module status row in \`qa/README.md\`; (2) move the completed sprint checklist from \`AGENT-NEXT-STEPS.md\` to the \`## Sprint History\` section of \`qa/README.md\`; (3) trim \`AGENT-NEXT-STEPS.md\` so it contains only the next sprint — never let it accumulate more than one active sprint.
-
-## QA Pipeline
-
-Stages must run in order. Never start a stage unless its prerequisite is met.
-
-| Stage | Task | Skill | Prerequisite |
-|---|---|---|---|
-| 1 | Analyze module | \`.github/skills/qa-module-analysis/SKILL.md\` | None |
-| 2 | Generate specifications | \`.github/skills/qa-spec-generation/SKILL.md\` | 00-inventory.md exists |
-| 3 | Generate test plan | \`.github/skills/qa-test-plan/SKILL.md\` | 05-test-scenarios.md exists |
-| 4 | Generate test cases | \`.github/skills/qa-test-cases/SKILL.md\` | Test plan exists |
-| 5 | Generate automation | \`.github/skills/qa-automation/SKILL.md\` | Specs approved, no PENDING-CODE |
-| 5b | Stabilize failing tests | \`.github/skills/qa-test-stabilization/SKILL.md\` | Failing tests exist |
-| 6 | Maintenance | \`.github/skills/qa-maintenance/SKILL.md\` | Application change delivered |
-| — | ADO integration | \`.github/skills/qa-ado-integration/SKILL.md\` | ADO enabled in config |
-
-## Project KB
-1. \`qa/README.md\`          — The Living Index: module status, sprint history, blockers, quick-start commands.
-2. \`qa/memory/INDEX.md\`    — Index of all memory files; load this before selecting which files to read.
-`;
-}

package/templates/qa-framework.instructions.md

@@ -0,0 +1,45 @@
+---
+applyTo: '**'
+---
+# QA Framework Instructions
+
+This project uses `@keber/qa-framework` v{{VERSION}} for spec-driven automated testing.
+
+## Agent behavior rules
+
+0. **On every conversation start:** check if `qa/AGENT-NEXT-STEPS.md` exists. If it does, read it and complete its steps before anything else.
+1. Before performing any QA task, load the relevant skill from `.github/skills/`. For project context, read `qa/memory/INDEX.md` if it exists, then load only the memory files relevant to the current task — do not load all memory files unconditionally. Never execute a pipeline stage unless its prerequisite is satisfied.
+2. Always save artifacts in the correct `qa/` subfolder - refer to `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`
+5. Read previous test suites code in `qa/07-automation/e2e/tests/` if available before writing new automation to maintain consistency in style and approach
+6. Project QA config is at `qa/qa-framework.config.json`
+7. Save learnings in `qa/memory/` with proper naming and metadata. Always update `qa/memory/INDEX.md` after adding or updating any memory file.
+8. **Sprint/module completion criteria:** A sprint or module is complete when every TC in scope has one of these three valid states - and no other: (a) `test()` passing: the app meets the spec; (b) `test.fail()`: the app violates the spec **and** a file `qa/06-defects/open/DEF-SIS-NNN_*.md` exists documenting which business rule is violated and what the app actually does; (c) `test.skip()`: the TC is not yet executable, annotated with `PENDING-CODE` and a linked issue. A sprint is **not** complete if any TC is failing without `test.fail()`, or has `test.fail()` without a defect file, or has `test.skip()` without a `PENDING-CODE` reason.
+9. **On sprint/module completion:** (1) update the module status row in `qa/README.md`; (2) move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`; (3) trim `AGENT-NEXT-STEPS.md` so it contains only the next sprint — never let it accumulate more than one active sprint.
+10. **Assertion polarity rule (BLOCKING):** A test must assert what the **spec** requires, not what the app currently does. If the app fails to meet the spec, use `test.fail()` + correct assertion to document the defect — **never invert or weaken an assertion to make a test go green.** A failing test that exposes a real defect is always more valuable than a passing test that hides one.
+11. **Character encoding safety (BLOCKING):** In ALL generated content (markdown, scripts, test titles, ADO fields, config files), never use characters at these Unicode code points: em-dash (U+2014), en-dash (U+2013), horizontal ellipsis (U+2026), smart/curly quotes (U+201C, U+201D, U+2018, U+2019), or directional arrows (U+2190-U+21FF). Use ASCII equivalents instead: ` - ` (hyphen with surrounding spaces) for dashes, `...` for ellipsis, `"` and `'` for quotes, `->` and `<-` for arrows. Exception: Latin Extended characters (U+00C0-U+024F) are always permitted - this covers Spanish vowels with accents (U+00E0-U+00FA), n with tilde (U+00F1/U+00D1), and u/o with umlaut (U+00FC/U+00DC, U+00F6/U+00D6).
+
+## Formatting rules for generated content
+1. Generate the output in `UTF-8` encoding without BOM (`UTF-8`, no signature).
+2. Ensure the raw output is `UTF-8` encoded with no `EF BB BF` bytes at the beginning.
+
+{{ADO_SECTION}}
+## QA Pipeline
+
+Stages must run in order. Never start a stage unless its prerequisite is met.
+
+| Stage | Task | Skill | Prerequisite |
+|---|---|---|---|
+| 1 | Analyze module | `.github/skills/qa-module-analysis/SKILL.md` | None |
+| 2 | Generate specifications | `.github/skills/qa-spec-generation/SKILL.md` | 00-inventory.md exists |
+| 3 | Generate test plan | `.github/skills/qa-test-plan/SKILL.md` | 05-test-scenarios.md exists |
+| 4 | Generate test cases | `.github/skills/qa-test-cases/SKILL.md` | Test plan exists |
+| 5 | Generate automation | `.github/skills/qa-automation/SKILL.md` | Specs approved, no PENDING-CODE |
+| 5b | Stabilize failing tests | `.github/skills/qa-test-stabilization/SKILL.md` | Failing tests exist |
+| 6 | Maintenance | `.github/skills/qa-maintenance/SKILL.md` | Application change delivered |
+| — | ADO integration | `.github/skills/qa-ado-integration/SKILL.md` | ADO enabled in config |
+
+## Project KB
+1. `qa/README.md`          — The Living Index: module status, sprint history, blockers, quick-start commands.
+2. `qa/memory/INDEX.md`    — Index of all memory files; load this before selecting which files to read.