@keber/qa-framework 1.11.3 → 1.12.0

package/README.md

@@ -1,7 +1,7 @@
 # qa-framework
 
 > Reusable, installable, agent-oriented QA framework for spec-driven automated testing.
-> Current version: **v1.10.0**
+> Current version: **v1.12.0**
 
 ---
 
@@ -176,7 +176,7 @@ qa/
 ├── {module}/{submodule}/        <- 6-file spec sets created per module/submodule in config
 ├── 02-test-plans/               <- Test plans (automated + manual)
 ├── 03-test-cases/               <- TC-*.md step-by-step docs (manual track; optional if fully automated)
-├── 04-test-data/                <- Shared test data factories/seeders (optional — per-module data lives in 01-specs)
+├── 04-test-data/                <- Shared test data factories/seeders (optional - per-module data lives in 01-specs)
 ├── 05-test-execution/           <- Execution reports and results
 ├── 06-defects/open|resolved/    <- Defect tracking
 ├── 07-automation/               <- Playwright automation code and config

package/docs/architecture.md

@@ -2,18 +2,18 @@
 
 ## Framework Architecture
 
-**Version**: 1.6.0  
-**Date**: 2026-04-29
+**Version**: 1.11.4  
+**Date**: 2026-07-08
 
 ---
 
 ## Design Goals
 
-1. **Decoupled core** — the framework works without Playwright, without Azure DevOps, without any specific CI/CD system
-2. **Layered optionality** — features are added as explicit opt-in integrations, not baked into the core
-3. **Agent-first design** — every convention exists so that an IDE agent can navigate and produce artifacts predictably
-4. **Spec-before-automation** — the specification layer is always the source of truth; automation references specs, never the reverse
-5. **Parameterization over hardcoding** — project-specific values live in `qa-framework.config.json`, not in framework files
+1. **Decoupled core** - the framework works without Playwright, without Azure DevOps, without any specific CI/CD system
+2. **Layered optionality** - features are added as explicit opt-in integrations, not baked into the core
+3. **Agent-first design** - every convention exists so that an IDE agent can navigate and produce artifacts predictably
+4. **Spec-before-automation** - the specification layer is always the source of truth; automation references specs, never the reverse
+5. **Parameterization over hardcoding** - project-specific values live in `qa-framework.config.json`, not in framework files
 
 ---
 
@@ -84,8 +84,10 @@
 │  ├── 08-azure-integration/       <- optional ADO integration                │
 │  └── memory/                     <- agent learnings (project-maintained)    │
 │                                                                             │
-│  .github/copilot-instructions.md <- generated (framework-owned)            │
+│  .github/instructions/qa-framework.instructions.md <- generated (framework) │
 │  .github/skills/                 <- copied from package (framework-owned)  │
+│  .claude/rules/qa-framework.md   <- generated (framework, Claude Code)     │
+│  .claude/commands/qa-*.md        <- generated (framework, Claude Code)     │
 └─────────────────────────────────────────────────────────────────────────────┘
 ```
 
@@ -98,12 +100,12 @@ Module analysis (agent)
         │
         ▼
 01-specifications/module-X/submodule-Y/
-  ├── 00-inventory.md       ← what exists in the UI
-  ├── 01-business-rules.md  ← RN-* identifiers
-  ├── 02-workflows.md       ← FL-* flowcharts
+  ├── 00-inventory.md       <- what exists in the UI
+  ├── 01-business-rules.md  <- RN-* identifiers
+  ├── 02-workflows.md       <- FL-* flowcharts
   ├── 03-roles-permissions.md
   ├── 04-test-data.md
-  └── 05-test-scenarios.md  ← TC-* identifiers  ──────────────────────┐
+  └── 05-test-scenarios.md  <- TC-* identifiers  ──────────────────────┐
                                                                        │
         │                                                              │
         ▼                                                              ▼
@@ -120,8 +122,8 @@ Module analysis (agent)
                               │
                               ▼
                [ADO enabled?]
-                  YES → playwright-azure-reporter syncs results to ADO Test Plan
-                  NO  → 05-test-execution/automated/{date}.md   (local report)
+                  YES -> playwright-azure-reporter syncs results to ADO Test Plan
+                  NO  -> 05-test-execution/automated/{date}.md   (local report)
                               │
                               ▼
                     06-defects/ (if test.skip for known bug)
@@ -132,18 +134,20 @@ Module analysis (agent)
 
 ## Layer Definitions
 
-### Layer 1 — Framework Core (mandatory)
+### Layer 1 - Framework Core (mandatory)
 
 Installed always. Contains:
 
 - `qa/` directory skeleton (10 folders)
-- `.github/skills/` — 8 agent skill sets (3-layer model: SKILL.md + references/)
-- `00-standards/` — naming conventions, templates
+- `.github/skills/` - 8 agent skill sets (3-layer model: SKILL.md + references/)
+- `00-standards/` - naming conventions, templates
 - `QA-STRUCTURE-GUIDE.md`
-- `.github/copilot-instructions.md` — generated pipeline sequencer
+- `.github/instructions/qa-framework.instructions.md` - generated pipeline sequencer (Copilot)
+- `.claude/rules/qa-framework.md` - generated pipeline sequencer (Claude Code, unconditional load)
+- `.claude/commands/qa-*.md` - generated thin wrappers, one per skill (Claude Code)
 - `qa-framework.config.json` schema
 
-### Layer 2 — Playwright Integration (opt-in)
+### Layer 2 - Playwright Integration (opt-in)
 
 Installed always (scaffold is always created by `init`):
 
@@ -156,7 +160,7 @@ Installed always (scaffold is always created by `init`):
 - `qa/07-automation/integration/README.md` (placeholder)
 - `qa/07-automation/load/README.md` (placeholder)
 
-### Layer 3 — Azure DevOps Integration (opt-in)
+### Layer 3 - Azure DevOps Integration (opt-in)
 
 Installed when `integrations.azureDevOps.enabled = true`:
 
@@ -173,11 +177,11 @@ Installed when `integrations.azureDevOps.enabled = true`:
 ```
 qa-framework.config.json  (project-level, committed to repo)
         │
-        ├── project.*           → Display values, URLs (non-secret)
-        ├── modules[]           → Module codes, paths, ADO IDs
-        ├── conventions.*       → Naming patterns, TC ID format
-        ├── testUsers[]         → Role→envVar mapping (NOT credentials)
-        └── integrations.*      → Feature flags + integration config
+        ├── project.*           -> Display values, URLs (non-secret)
+        ├── modules[]           -> Module codes, paths, ADO IDs
+        ├── conventions.*       -> Naming patterns, TC ID format
+        ├── testUsers[]         -> Role->envVar mapping (NOT credentials)
+        └── integrations.*      -> Feature flags + integration config
                 │
                 └── credentials come from:
                       .env  (local, gitignored)
@@ -227,6 +231,6 @@ Full rules: [docs/folder-structure-guide.md](folder-structure-guide.md)
 
 1. The primary test runner is Playwright. Other runners (Jest, Cypress) are not excluded but are not provided adapters in v1.0.
 2. The target application runs in a browser. Back-end API-only testing is not the primary use case of this framework (though API testing can be added to `07-automation/` as needed).
-3. The IDE agent is GitHub Copilot or equivalent. The instructions are written in Markdown and are IDE-agnostic.
+3. The IDE agent is GitHub Copilot, Claude Code, or equivalent. The instructions are written in Markdown and are IDE-agnostic; `init`/`upgrade` generate native artifacts for both Copilot (`.github/instructions/`) and Claude Code (`.claude/rules/`, `.claude/commands/`) in parallel, without detecting which agent the consumer uses.
 4. The project uses Git. The `qa/` directory lives inside the same repository as the application code (monorepo-friendly).
 5. Credentials are always managed via environment variables. There is no fallback to hardcoded credentials in any framework file.

package/docs/decisions/lane-heartbeat-caller.md

@@ -0,0 +1,86 @@
+# Decision: the dispatcher calls the lane heartbeat, not the executor
+
+**Status**: accepted, not implemented
+**Date**: 2026-09-08
+**Scope**: the N-lane work still pending upstream (FRAMEWORK-FIXES v3 items 1-4, v5 items 1, 2, 4)
+
+---
+
+## Context
+
+Parallel QA lanes exist to work around a constraint of the applications under test:
+one account cannot hold two sessions at once, so a second login silently invalidates
+the first. A lane lock assigns each concurrent worker its own account.
+
+A lock is only useful if a held lane stays held. The reference implementation
+(`lane-lock.js` in the Sispro Exportadora project) frees a lane when it looks stale,
+using a composite predicate: the acquisition is older than 20 minutes AND either no
+heartbeat was ever sent OR the last heartbeat is itself older than 20 minutes. A
+recent heartbeat proves the holder is alive, so the lane is never swept.
+
+That predicate is only as good as whoever calls `heartbeat`.
+
+## The incident that forced the decision
+
+On 2026-08-22 a delegated sub-agent spent over 20 minutes on a legitimate live
+investigation - genuine environment congestion, 80 to 90 concurrent browser and node
+processes - and never called `heartbeat`. The sweep did exactly what it was written
+to do and freed the lane while the sub-agent was still driving that account: the
+precise scenario the heartbeat exists to prevent.
+
+No cross-session collision followed, but only because a person noticed the lane was
+free with no matching completion report, paused the sub-agent, confirmed by explicit
+reply that nothing had run against the browser after the sweep, and re-reserved the
+lane. The protection failed by design and was caught by attentiveness.
+
+## Decision
+
+**The dispatcher calls `heartbeat` from its own wait loop.** The executor is not
+required to call it and must not be relied upon to.
+
+## Why
+
+The executor option fails for a structural reason, not a discipline one. A delegated
+agent has no reason to discover `heartbeat` unless the dispatching prompt tells it,
+every single time. That is the same failure this project has now recorded four times
+over: a known-issues record that existed and was not consulted, an orthography rule
+that was asserted rather than measured, and this heartbeat. A mechanism whose
+protection depends on correctly instructing an uninstructed party is not a control.
+
+The dispatcher, by contrast, already knows whether the task is still running - it can
+query task state directly. The executor cannot see how long it has been between its
+own tool calls. Putting the call where the knowledge already is removes the
+instruction step entirely, which is where option 1 actually broke.
+
+The cost is real and accepted: the dispatcher's wait loop becomes more complex, and
+the concrete implementation is agent-specific rather than framework-generic.
+
+## Layering
+
+This follows the split established in FRAMEWORK-FIXES v3 section 5.
+
+The agent-agnostic framework states the requirement: a lane must be acquired through
+the lock before any worker is dispatched against it, released when the work ends, and
+kept alive by the dispatcher while the work is in flight. Each agent's adaptation
+prescribes the mechanism. For Claude Code that means a `/loop` wrapper with a
+`ScheduleWakeup` fallback and a non-blocking task-state check - primitives that have
+no equivalent in other agents, and so must not be written into
+`templates/qa-framework.instructions.md`.
+
+## Consequences
+
+- The N-lane scaffold ships `heartbeat` together with the rule naming its caller.
+  Shipping the sweep without that answer reproduces the 2026-08-22 incident in every
+  project that adopts it.
+- A lane held far longer than the application's session TTL is a signal to verify,
+  not a defect to ignore. Each project's agent-specific instructions must define how
+  it verifies a lock is still legitimately held and how it clears a stale one.
+- Neither option was implemented in the originating project, so there is no verified
+  reference implementation of the dispatcher-side loop to lift. It has to be written.
+
+## Sources
+
+- `temp/FRAMEWORK-FIXES-qa-framework-v5.md` item 5, which framed the fork and
+  recommended this side.
+- `temp/FRAMEWORK-FIXES-qa-framework-v3.md` section 5, for the agent-agnostic versus
+  agent-specific split.

package/docs/final-report.md

@@ -1,4 +1,4 @@
-# Phase 6 — Final Report: keber/qa-framework
+# Phase 6 - Final Report: keber/qa-framework
 
 **Date**: 2025-01-15
 **Version analyzed**: 1.0.0
@@ -26,29 +26,29 @@ procedures documented in `MIGRATION-NOTES.md`.
 
 ## 2. Source Repository Findings
 
-### Repo A — redacted-repo-web
+### Repo A - redacted-repo-web
 
 | Category | Finding |
 |----------|---------|
 | Stack | ASP.NET MVC 5 + Web API 2 + SQL Server |
 | Frontend | jQuery + Select2 + toastr + SweetAlert2 + Metronic |
 | Auth | RUT-based login (`#m_login_signin_submit`) |
-| QA maturity | Medium — spec files present, standards missing |
+| QA maturity | Medium - spec files present, standards missing |
 | Automation | Sprint 40: 26 P0 tests (24 pass, 2 skip via DEF-001/DEF-002) |
 | ADO | Referenced (Plan 21992/Suite 21993) but not reporter-integrated |
 | Modules | 7 submodules documented (~160 TCs across 82 QA files) |
 | Strengths | EXEC_IDX pattern, POM structure, multi-role auth, skip+DEF |
 | Gaps | No `00-standards/`, no `08-azure-integration/`, no session summaries |
 
-### Repo B — redacted-repo
+### Repo B - redacted-repo
 
 | Category | Finding |
 |----------|---------|
 | Stack | Blazor WebAssembly + .NET + Radzen components |
 | Auth | Email-based (`#email-input` / `#password-input`) |
-| QA maturity | High — complete standards folder, ADO fully integrated |
+| QA maturity | High - complete standards folder, ADO fully integrated |
 | Automation | 67 automated TCs (53 pass / 2 fail / 12 skip) |
-| ADO | Full: Plans 22304/22794/22875, WI IDs 22957–23034, bi-directional sync |
+| ADO | Full: Plans 22304/22794/22875, WI IDs 22957-23034, bi-directional sync |
 | Modules | 4 modules × 17+ submodules (~894 TCs) |
 | Strengths | `00-standards/`, `08-azure-integration/`, module-registry, ado reporter |
 | Gaps | No EXEC_IDX pattern, no POM convention, no session summaries |
@@ -61,9 +61,9 @@ procedures documented in `MIGRATION-NOTES.md`.
 |---------|--------|----------|
 | 6-file submodule spec pattern | Both | Core framework pattern |
 | Playwright `@playwright/test` | Both | Standard automation library |
-| Priority levels P0–P3 | Both | Universal tagging via `@PX` |
+| Priority levels P0-P3 | Both | Universal tagging via `@PX` |
 | `test.skip()` + DEF reference | Repo A | Adopted as standard skip convention |
-| `06-defects/` folder | Repo A | Optional — recommended without ADO |
+| `06-defects/` folder | Repo A | Optional - recommended without ADO |
 | `00-standards/` folder | Repo B | Adopted; templates included |
 | `08-azure-integration/` folder | Repo B | Optional; fully documented |
 | `module-registry.json` | Repo B | Included in ADO integration |
@@ -85,7 +85,7 @@ procedures documented in `MIGRATION-NOTES.md`.
 | RUT-based username field | Repo A | Parameterized via `QA_LOGIN_EMAIL_SELECTOR` |
 | `#email-input` / `#password-input` | Repo B | Parameterized via env vars |
 | ADO Plan IDs (21992, 22304, etc.) | Both | Parameterized via `QA_ADO_PLAN_ID` |
-| ADO WI IDs (22957–23034) | Repo B | Injected per-project via inject-ado-ids.ps1 |
+| ADO WI IDs (22957-23034) | Repo B | Injected per-project via inject-ado-ids.ps1 |
 | Specific module names/selectors | Both | Remain in project-specific spec files |
 | Sprint numbers | Both | Remain in project-specific test plans |
 | Metronic theme selectors | Repo A | Project-specific; documented in Repo A specs |
@@ -110,7 +110,7 @@ Fifteen formal decisions were made and documented in `docs/generalization-decisi
 | §8 | POM pattern | Recommended (Repo A); inline acceptable |
 | §9 | Standards folder | Adopted from Repo B (more complete) |
 | §10 | Session summaries | New addition to both repos' patterns |
-| §11 | Priority levels | P0–P3 universal; `@P0` grep-tag convention |
+| §11 | Priority levels | P0-P3 universal; `@P0` grep-tag convention |
 | §12 | `08-azure-integration/` | Optional; fully documented scripts |
 | §13 | CI pipeline | Parameterized `azure-pipeline-qa.yml` |
 | §14 | Framework distribution | npm package (`keber/qa-framework`) |
@@ -122,23 +122,23 @@ Fifteen formal decisions were made and documented in `docs/generalization-decisi
 
 ```
 qa-framework/
-├── package.json                          ← npm package, CLI entry
-├── qa-framework.config.json             ← example project config
+├── package.json                          <- npm package, CLI entry
+├── qa-framework.config.json             <- example project config
 ├── README.md
 ├── CHANGELOG.md
 ├── MIGRATION-NOTES.md
 │
 ├── docs/
-│   ├── architecture.md                  ← 4-layer component map
-│   ├── comparison-matrix.md             ← Phase 1 artifact
-│   ├── generalization-decisions.md      ← Phase 2 artifact (15 decisions)
-│   ├── installation.md                  ← 3 install options
-│   ├── spec-driven-philosophy.md        ← Core methodology
-│   ├── folder-structure-guide.md        ← Full folder reference
-│   ├── usage-with-agent.md              ← Agent prompt patterns
-│   └── final-report.md                  ← This file
+│   ├── architecture.md                  <- 4-layer component map
+│   ├── comparison-matrix.md             <- Phase 1 artifact
+│   ├── generalization-decisions.md      <- Phase 2 artifact (15 decisions)
+│   ├── installation.md                  <- 3 install options
+│   ├── spec-driven-philosophy.md        <- Core methodology
+│   ├── folder-structure-guide.md        <- Full folder reference
+│   ├── usage-with-agent.md              <- Agent prompt patterns
+│   └── final-report.md                  <- This file
 │
-├── agent-instructions/                  ← Consumed by Copilot agent
+├── agent-instructions/                  <- Consumed by Copilot agent
 │   ├── 00-module-analysis.md
 │   ├── 01-spec-generation.md
 │   ├── 02-test-plan-generation.md
@@ -148,7 +148,7 @@ qa-framework/
 │   └── 06-maintenance.md
 │
 ├── templates/
-│   ├── specification/                   ← 6-file submodule template set
+│   ├── specification/                   <- 6-file submodule template set
 │   │   ├── 00-inventory.md
 │   │   ├── 01-business-rules.md
 │   │   ├── 02-workflows.md
@@ -188,7 +188,7 @@ qa-framework/
 │           ├── 00-inventory.md
 │           └── suppliers-create.spec.ts
 │
-└── scripts/                             ← CLI implementation
+└── scripts/                             <- CLI implementation
     ├── cli.js
     ├── init.js
     ├── generate.js