@keber/qa-framework 1.11.3 → 1.13.0

package/CHANGELOG.md

@@ -7,6 +7,346 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [1.13.0] - 2026-11-04
+
+Dated by its release, not by its bump. `package.json` was moved to `1.13.0` on 2026-10-16,
+but the version was never tagged or published, so everything below ships together under
+this number. The infrastructure fixes listed in Added and Fixed were written later, on the
+branch that unblocked this release.
+
+### Added
+
+- `templates/agents/qa-reporte-ejecucion.md` - new Claude Code agent that exports the ADO
+  test plan results, versions the raw export under `ado-export-<YYYY-MM-DD>/` and writes the
+  sprint `Reporte-de-Ejecucion-de-Pruebas-<project>-Sprint-<N>.md` (summary with executed,
+  success and coverage metrics, plus promoted findings).
+- `templates/agents/qa-investigador.md` - new Claude Code agent that investigates one root
+  cause against the real environment. Its tools are generated from `parallelLanes`: each lane
+  with an `mcpNamespace` adds 15 Playwright MCP browser tools, a lane table and the mandatory
+  heartbeat protocol; with no MCP lane it gets a no-browser section instead.
+- Agent template engine: `{{#if FLAG}}` / `{{#unless FLAG}}` blocks, single-pass placeholder
+  replacement and a guard that fails on any unresolved `{{...}}` token.
+- New placeholders: `INVESTIGATOR_TOOLS`, `LANE_MCP_TABLE`, `APPROVAL_THRESHOLD_PERCENT`,
+  `APPROVAL_THRESHOLD_RATIO`, `DECIMAL_SEPARATOR`, `TC_ID_PATTERN`, `QA_BASE_URL`,
+  `LOGIN_PATH`, `TECH_STACK`.
+- Config keys: `integrations.azureDevOps.sprintCycle.approvalThresholdPercent` (default 85),
+  optional `conventions.decimalSeparator` and `conventions.defectIdPrefix`. Documented in
+  `qa-framework.config.schema.json`, together with the `mcpNamespace` pattern.
+- `qa-framework validate` checks present-but-invalid values of those keys and of
+  `parallelLanes`, and now finds the config under `qa/` as well as at the project root.
+- **`scripts/lib/module-keys.js`** - single source of truth for how a module key maps
+  to a spec folder (prefixed) and to an automation folder (bare). Shared by `init.js`
+  and `validate.js` so the two cannot drift apart again.
+- **`scripts/sync-version.js`** - now also rewrites `frameworkVersion` in
+  `qa-framework.config.json`, by field rather than by the loose `vX.Y.Z` prose pattern.
+- **`test/module-keys.test.js`, `test/sync-version.test.js`** - unit coverage for the
+  key helpers plus a drift guard that fails CI whenever a published version surface
+  disagrees with `package.json`.
+- **`.github/workflows/publish.yml`** - the suite now runs before `npm publish`.
+  `ci.yml` triggers on pushes to `main` and on pull requests, so it never sees a tag,
+  and publishing is triggered by a tag push: nothing was verified on the path that
+  actually reaches npm. The drift guard above only protects a release once it runs
+  there.
+
+### Changed
+
+- `init` and `upgrade` generate six agents (was four) when `sprintCycle.enabled` is true.
+  Agents are rendered independently: an invalid lane config fails `qa-investigador` only,
+  the other five are still written and the command exits 1.
+- As npm postinstall (`init --skip-if-exists`), an agent that cannot be rendered is reported
+  as a WARNING naming the agent and asking to fix the config and run
+  `npx qa-framework upgrade`; postinstall exits 0 so `npm install` does not fail. Explicit
+  `init` and `upgrade` keep exit code 1.
+- `qa-informe-resultados` reads its approval threshold from config instead of a hardcoded
+  85% and states the decimal separator rule.
+
+### Fixed
+
+- `qa-informe-resultados` looked for `Reporte-de-Ejecucion-de-Pruebas-...` and pointed to the
+  `qa-ado-integration` skill, which does not produce that file. It now names the
+  `qa-reporte-ejecucion` agent, the canonical filename (active and historical sprint folders)
+  and accepts the older `Reporte-ejecución-de-pruebas-*` files.
+- `templates/qa-framework.instructions.md` and `templates/qa-framework.rules.md` carried a
+  project-specific `DEF-SIS-NNN` example; it is now `DEF-{PREFIX}-NNN`.
+- **`scripts/init.js`** - module spec folders are now scaffolded as
+  `qa/01-specifications/module-{name}/submodule-{name}/`, the layout declared by every
+  skill, by `docs/folder-structure-guide.md` and by the `specPath` field of
+  `qa-framework.config.json`. init.js wrote the bare key, so a freshly scaffolded
+  project violated the spec-path convention its own agent instructions impose.
+  Prefixing is idempotent: a config whose key already reads `module-suppliers` is not
+  turned into `module-module-suppliers`.
+- **`scripts/init.js`** - automation stubs and test case ids keep using the **bare**
+  key (`e2e/tests/suppliers/create.spec.ts`, `TC-SUPPLIERS-CREATE-001`), matching the
+  `automationPath` field and the live consuming projects. Only the spec tree is
+  prefixed.
+- **`scripts/validate.js`** - `--strict` strips the `module-` / `submodule-` prefix
+  before deriving the automation path. It was pointing the warning at
+  `e2e/tests/module-{name}/`, a folder no project has ever created.
+- **`qa-framework.config.json`** - `frameworkVersion` was stuck at `1.10.0` while the
+  package shipped `1.12.0`. The file is published and is the template copied into every
+  consuming project, where the value is injected into `{{VERSION}}` of the generated
+  agent instructions, so every fresh install since 1.11.0 reported the wrong version.
+- **`package.json`** - the npm `version` lifecycle script now also stages
+  `qa-framework.config.json`. sync-version.js rewrites it, but the staging list did not
+  include it, so the release commit and its tag would have carried the OLD
+  frameworkVersion - and the publish workflow builds from a clean checkout of that tag,
+  reintroducing the exact drift this change set out to fix.
+- **`test/sync-version.test.js`** - two tests compared files against their starting bytes,
+  which assumed the tree was already synced. On a drifted tree one of them ran
+  `sync-version` and left `qa-framework.config.json` rewritten: the first run failed, the
+  retry passed, and the drift vanished from the working tree unnoticed. A suite that edits
+  tracked files turns a red run green on the retry and hides what it exists to catch.
+- **`test/init.test.js`** - the agent summary assertion matched only the forward-slash form
+  of `.claude/agents/` and took the first matching line. `init.js` prints those lines
+  through `path.relative`, so on Windows the per-file `[created]` lines never matched and it
+  landed on the summary line, while on Linux it landed on the first `[created]` line. The
+  test passed locally and failed the first time it ran on CI.
+
+---
+
+## [1.12.0] - 2026-09-08
+
+Reconstructed from `4fe32fb..f52257a` (39 commits). Minor rather than major: a project
+with no `parallelLanes` block behaves exactly as before, `PENDING-BROWSER` adds an enum
+value without removing any, and the spec-path change affects what `init` generates from
+then on, not what already exists. The one user-visible break is `engines` moving from
+`>=18` to `>=20`.
+
+### Added
+
+- **`parallelLanes` lane table** - `qa-framework.config.json` gains a lane block and
+  `qa-framework.config.schema.json` is published alongside it. A lane is four coupled
+  values (account env prefix, `storageState`, MCP namespace, runner project), none of
+  which can be inferred from the others, plus per-lane capabilities: a project can have
+  six accounts but only three MCP servers. A project with no block, or `enabled: false`,
+  resolves a single implicit default lane.
+- **`templates/automation-scaffold/scripts/lane-lock.js`** - config-driven lane lock
+  ported from the reference implementation. `acquire` (random free lane, queues) and
+  `reserve` (exact lane, no queue, throws when busy) stay two separate verbs; staleness
+  is a composite predicate (past the threshold AND no recent heartbeat); the lock
+  directory resolves by shell > `.env` > per-checkout precedence and the resolved path
+  and its source are reported on stderr. Reads `.env` with `dotenv.parse()`, never
+  `config()`, so a script whose only job is choosing a directory never gains ambient
+  access to the QA account passwords in the same file.
+- **`templates/automation-scaffold/scripts/global-setup-guards.js`** - `global-setup`
+  performs the only login, so it is the last point at which a run about to drive an
+  account it does not hold can be stopped. `assertColdSetupIsIntentional` throws before
+  any login when neither `QA_LANE_ONLY` nor `QA_COLD_SETUP=1` is set, since a cold setup
+  re-logs in every lane and invalidates other running sessions; `assertLaneIsLocked`
+  verifies outside CI that the lane is held; `assertProjectsMatchLane` catches a
+  `--project` whose `storageState` points at a different lane than the one reserved.
+  Plain CommonJS so it is testable with `node --test` without adding `ts-node`.
+- **`templates/automation-scaffold/scripts/lane-config.js`** - lane table resolver shared
+  by the config and the guards.
+- **`templates/qa-framework.rules.md`** plus **`templates/agents/`** - four agent
+  templates (`qa-analisis.md`, `qa-asesoria.md`, `qa-plan.md`,
+  `qa-informe-resultados.md`) for analysis, sprint advisory, test planning and ADO result
+  reporting, deployed through `scripts/lib/claude-agents.js` and
+  `scripts/lib/claude-commands.js`.
+- **`scripts/check-forbidden-chars.js`** (`npm run check-chars`) - enforces the BLOCKING
+  character-safety rule the package stated but never checked. Flags em-dash, en-dash,
+  ellipsis, smart quotes and arrows; leaves Latin Extended and emoji alone. Reports
+  `file:line:column` with the code point and its ASCII replacement.
+- **`scripts/check-spanish-accents.js`** (`npm run check-accents`) - language-aware accent
+  gate for Markdown. Classification is the hard part, not detection: it measures the
+  density of Spanish function words in prose only, after stripping fenced code, inline
+  code, link targets, tags, placeholders and paths. Against this package's corpus English
+  lands at 0.000-0.001 and Spanish templates at 0.125-0.165, with the threshold at 0.07;
+  a test asserts the gap stays wide.
+- **`scripts/sync-version.js`** - wired into the `npm version` lifecycle to keep
+  `README.md` and `.github/copilot-instructions.md` aligned with `package.json`.
+- **Test suite and CI** - black-box tests for `cli.js`, `init.js`, `validate.js`,
+  `upgrade.js`, the lane scripts and both character gates, using Node's built-in runner
+  with no new devDependency, plus `.github/workflows/ci.yml`.
+- **`scripts/upgrade.js` section 9** - carries the v1.12.0 scaffold into existing
+  projects. `upgrade` force-copied only `.github/skills/`, `copilot-instructions.md` and
+  `QA-STRUCTURE-GUIDE.md`, so everything this release changed under `templates/` reached
+  new projects through `init.js` alone and existing installations kept the old scaffold,
+  including the login that types the password with `fill()`. The rule is per file:
+  overwrite what is framework-owned, warn and continue where overwriting would destroy
+  working user code, and treat a dependency group as all-or-nothing, since
+  `playwright.config.ts` and `global-setup.ts` both `require()` the lane scripts and a
+  partial install leaves a project that cannot start Playwright. Baseline detection is
+  content-hash based, not `frameworkVersion` based: the recorded values in live projects
+  were `1.10.0`, `1.1.3`, `1.1.3` and `1.0.0`, two of them malformed. Files left
+  user-owned are scanned for `.fill(password)` and reported with file and line, without a
+  textual patch.
+- **`PENDING-BROWSER`** - fourth value in the TC Origin vocabulary, for an element
+  observed and confirmed to exist whose behavior could not be exercised end to end.
+  Without it agents either overclaim with `UI-OBSERVED` or misuse `PENDING-CODE`, which
+  pollutes gap tracking downstream.
+- **Known-issues lookup before defect creation** - nothing required checking whether a
+  defect had already been filed. The gate distinguishes the two outcomes that matter: an
+  open match is referenced instead of refiled, a closed match is filed as a regression.
+  `templates/defect-report.md` gains the section that records the search.
+- **Stage 5 gates** - `tsc --noEmit` plus a single smoke run of a newly written spec
+  before the submodule is marked complete. Both run before the completion checklist; a
+  full green suite remains Stage 5b's job.
+- **Closing measurement for doc-generating stages** - the four skills that write Markdown
+  now end on evidence (accent count, forbidden characters, BOM) rather than a compliance
+  claim, with the language boundary stated so English artifacts are not asked for accents
+  they should not have.
+- **`skills/qa-automation/references/pom-template.md`** - page-object template taken from
+  real project use: an abstract per-module CRUD base plus thin per-submodule classes,
+  with the accent-insensitive label matching that pattern needs against Spanish UIs.
+- **`MIGRATION-NOTES.md`**, **`docs/decisions/lane-heartbeat-caller.md`** and
+  **`docs/visuals/`** - embedded-QA migration guidance, the record that the dispatcher
+  (not the executor) calls heartbeat, and the diagrams referenced from the architecture
+  docs.
+
+### Changed
+
+- **`engines`** - `>=18` becomes `>=20`, and CI tests Node 20, 22 and 24. The matrix had
+  been testing 18 and 20, both out of maintenance, while `publish.yml` released on 24,
+  which no job tested. Users on 18 now get an npm warning, which is the point.
+- **`templates/*/playwright.config.ts`** - both configs called `dotenv.config()`, which
+  injects the entire `.env` into `process.env`. In a real project that file holds every QA
+  account password plus ADO tokens (82 lines in one case) while these configs need a
+  handful of non-secret values. They now read an explicit key list with `dotenv.parse()`,
+  which returns a plain object and never touches `process.env`, and only fill keys the
+  environment has not already set, so shell and CI variables still win.
+- **`templates/automation-scaffold/playwright.config.ts`** - runner projects and auth are
+  generated from the lane table, replacing the commented-out
+  `chromium-user1` / `chromium-user2` block that sat outside the `projects` array and
+  could not have worked as written. `storageState` is derived through lane-lock rather
+  than hardcoded: a parallel hardcoded mapping caused real evidence corruption once, a run
+  recorded under the wrong account because the project was pinned to one lane while
+  `QA_LANE_ONLY` named another.
+- **`global-setup.ts`** - `resolveAuthUsers` resolved lanes by substring
+  (`storageState.includes('user-2')`, which also matches `user-20`) and had no branch for
+  a third lane. It now matches the lane table exactly and reads credentials from each
+  lane's declared account prefix.
+- **Agent behavior rules** - a BLOCKING lane-lock rule states the requirement only
+  (acquire before dispatching, release when done, dispatcher keeps the lane alive, queue
+  or reject at the cap, never force past it), agent-agnostic so each agent's adaptation
+  prescribes its own mechanism.
+- **`qa-test-plan` / `qa-test-cases`** - skill content consolidated into the templates;
+  `priority-and-feasibility.md` merged into `plan-de-pruebas-template.md`.
+- **Typographic characters** - em-dashes, en-dashes, arrows, smart quotes and ellipses
+  replaced with ASCII across `scripts/`, `skills/`, `templates/`, `docs/`, `examples/`,
+  `integrations/` and the PowerShell scripts. Substitution is context-sensitive: padded
+  prose dashes become ` - `, numeric and label ranges keep a tight hyphen, standalone
+  table cells become a bare `-`, and ASCII rules keep their original column width.
+  `CHANGELOG.md` keeps its historical occurrences deliberately - rewriting past entries to
+  satisfy a rule adopted later would falsify the log.
+
+### Fixed
+
+- **`scripts/init.js`** - module specs are scaffolded under
+  `qa/01-specifications/{module}/{submodule}/`. init wrote them to `qa/{module}/`, leaving
+  `01-specifications/` permanently empty while scattering specs as siblings of the
+  numbered folders. The existing tests ran with no config, so the module loop iterated
+  zero times and no spec path was ever asserted.
+- **`scripts/validate.js`** - check 2 walked all of `qa/`, treating every top-level
+  directory as a module, so it read `01-specifications/` as the module and demanded the 6
+  spec files one level above where they exist. The scan is now rooted at
+  `01-specifications/`, which also stops sibling folders such as `02-test-plans/` and
+  `memory/` from being mistaken for submodules; the `SKIP_DIRS` denylist is removed rather
+  than extended.
+- **`scripts/validate.js`** - `--strict` looked for automation specs at
+  `e2e/{module}/{submodule}.spec.ts`, a path nothing creates. `init.js` writes to
+  `e2e/tests/{module}/` and `upgrade.js` documents the v1.6.0 migration that moved them
+  there, so `--strict` emitted a permanently false warning for every submodule in all
+  three live projects.
+- **`scripts/validate.js`** - stopped requiring `05-test-plans`, a stale name from an
+  older convention; the current structure uses `05-test-execution` with test plans under
+  `02-test-plans`.
+- **`templates/*/fixtures` and both scaffolds** - the four remaining `fill(password)` call
+  sites are listed under Security below.
+- **`templates/agents/`** - the four Spanish-language agent templates shipped entirely
+  accent-stripped (144, 190, 88 and 52 Spanish markers, 0 to 2 accented characters between
+  them). This is functional, not cosmetic: page objects locate fields by visible label, so
+  a spec written as `Codigo` never matches a UI rendering the accented form. In one
+  project that cost 24 of 39 failing smoke tests and two wrong mitigations before the
+  cause was found.
+- **`templates/defect-report.md`** - the defect ID prefix is a placeholder. The template
+  hardcoded `DEF-{{NNN}}` while `defectIdPattern` carried `DEF-{NUM}`, and real projects
+  use a project prefix such as `DEF-SIS-014`.
+- **`templates/qa-framework.instructions.md` and `qa-framework.rules.md`** - referenced
+  `integrations.ado.enabled`, a config path that never existed. The real schema is
+  `integrations.azureDevOps.enabled`.
+- **`skills/qa-spec-generation`** - pointed at `references/spec-file-formats.md`, which
+  only exists under `qa-module-analysis/references/`, so Stage 2 could not find the
+  template it is told to use. `skills/qa-automation` referenced a `pom-template.md` that
+  did not exist.
+- **`qa-test-stabilization`** - the official suite is the only source of truth. A polling
+  diagnostic script saw a toast 4 of 4 times while the official suite saw none, 6 of 6
+  across two independent runs, and the defect had already been closed on that standalone
+  evidence. Standalone output is now diagnostic input, never a verdict.
+- **`templates/*/.env.example`** - both files carried a UTF-8 BOM and three em-dashes. A
+  BOM in a `.env` is not cosmetic: some parsers read the first key as `QA_BASE_URL`
+  and silently fail to find it, and these files ship to every consuming project as the
+  template developers copy to `.env`. The character gate's extension list gains
+  `.example` and `.ps1`, both previous blind spots.
+- **CI** - the test script used `test/**/*.test.js`, which needs globstar the runner's
+  shell does not enable, and the follow-up fix kept the pattern quoted so node received a
+  literal path. The validate step ran against this repository's own gitignored `qa/`
+  directory and failed with four missing-folder errors; it now scaffolds a throwaway
+  project and validates that, which exercises the contract that actually matters - what
+  `init.js` generates must pass `validate.js`.
+
+### Security
+
+- **Password no longer reaches Playwright traces.** Both scaffolds typed the QA password
+  with `locator().fill(password)`, and the automation scaffold ships `trace` and `video`
+  set to `retain-on-failure`, so any failed CI run persisted an artifact containing the
+  plaintext password. All four call sites - `global-setup.ts` in both scaffolds,
+  `fixtures/base.ts` (TTL-aware reauth) and `fixtures/auth.ts` (`loginAs`) - now set the
+  value through `page.evaluate()`, the mechanism this package already documented as
+  "Pattern 7: Password Injection (Trace Safety)". The fixture sites carried more exposure
+  than `global-setup`, which runs once per run, since reauth runs for every test past the
+  TTL and `loginAs` for every test that logs in as a role. Bubbling `input` and `change`
+  events are dispatched after the assignment because a bare `.value` write does not notify
+  the Blazor/Radzen-style frameworks these scaffolds target, and an explicit visible
+  `waitFor` replaces the auto-wait `fill()` provided. Email `fill()` calls are left in
+  place: emails are not secret and aid debugging. There are no remaining
+  `fill(password)` call sites in `templates/`.
+- **`.env` is no longer loaded wholesale** by the Playwright configs or the lane lock. See
+  Changed above.
+
+---
+
+## [1.11.3] - 2026-06-24
+
+Reconstructed from `5507f1a..4fe32fb`. Release plumbing only.
+
+### Changed
+
+- **`.github/workflows/publish.yml`** - `actions/checkout` and `actions/setup-node` move
+  from v4 to v6, and the publish job's Node version from 20 to 24.
+
+### Removed
+
+- **`NODE_AUTH_TOKEN` / `secrets.NPM_TOKEN`** from the publish step, completing the move
+  to npm trusted publishing begun in 1.11.1: the job now authenticates with the
+  short-lived OIDC token the `id-token: write` permission grants, so no long-lived npm
+  token is stored in the repository.
+
+No package content changed. Nothing reached consuming projects.
+
+---
+
+## [1.11.2] - 2026-06-24
+
+Version bump only - a republish of 1.11.1 after a failed publish run. No source,
+template, skill or script change; the diff is `package.json` and `package-lock.json`.
+
+---
+
+## [1.11.1] - 2026-06-24
+
+Reconstructed from `3a29617..59f6fe0`. Release plumbing only.
+
+### Added
+
+- **`.github/workflows/publish.yml`** - `id-token: write` permission on the publish job,
+  the prerequisite for npm trusted publishing. The long-lived token it replaces is dropped in
+  1.11.3.
+
+No package content changed. Nothing reached consuming projects.
+
+---
+
 ## [1.11.0] - 2026-06-24
 
 ### Added

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.13.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
@@ -245,6 +245,46 @@ See [docs/skills-architecture.md](docs/skills-architecture.md) for the full desi
 
 ---
 
+## Claude Code Sprint Agents (optional)
+
+When `integrations.azureDevOps.sprintCycle.enabled` is `true`, `init` (only if missing) and
+`upgrade` (always, framework-owned) generate six Claude Code subagents under `.claude/agents/`:
+
+| Agent | What it does |
+|---|---|
+| `qa-analisis` | Sprint analysis document: test universe, automation feasibility, P0-P3 prioritization, traceability matrix |
+| `qa-plan` | Sprint test plan: executive summary plus a trace-linked test case table that fits the manual-testing timebox |
+| `qa-asesoria` | Chat-only QA advisory (no `Write`/`Bash`) |
+| `qa-reporte-ejecucion` | Exports the ADO test plan results (via the `ado-qa` `getADO.ps1` script), versions the raw export by date and writes `Reporte-de-Ejecucion-de-Pruebas-<project>-Sprint-<N>.md` |
+| `qa-informe-resultados` | Narrative sprint closing report (metrics, failures, risks, QA verdict) built from the Reporte above |
+| `qa-investigador` | Investigates one concrete root cause against the real environment and returns a verdict with evidence; drives a browser over Playwright MCP when lanes provide one |
+
+Config keys read by the agents (all optional; defaults shown):
+
+| Key | Default | Used for |
+|---|---|---|
+| `integrations.azureDevOps.sprintCycle.approvalThresholdPercent` | `85` | Success rate over executed cases required for "Aprobado con observaciones" |
+| `integrations.azureDevOps.sprintCycle.sprintDurationDays` / `manualTestingTimeboxDays` | `8` / `2` | Sprint planning agents |
+| `integrations.azureDevOps.sprintCycle.dateFormat` / `timezone` | `dd-mm-aaaa` / `America/Santiago` | Dates in generated documents |
+| `conventions.decimalSeparator` | derived: `,` for `es*` locales or no locale, `.` otherwise | Percentages in reports |
+| `conventions.defectIdPrefix` | derived from `project.name` (uppercased) | Local defect candidate ids `DEF-<prefix>-NNN` |
+| `conventions.testCaseIdPattern` | `TC-{MODULE}-{SUBMODULE}-{NUM}` | Local ids kept out of ADO-facing documents |
+| `project.qaBaseUrl` / `loginPath` / `techStack` | "(no configurado: ...)" | Environment context for `qa-investigador` |
+
+`qa-investigador` and `parallelLanes`:
+
+- **0 MCP lanes** (no `parallelLanes`, `enabled: false`, or no lane with `mcpNamespace`): tools are
+  `Read, Write, Edit, Grep, Glob, Bash` and the agent investigates through code, config, logs and the
+  CLI runner, reporting browser-only hypotheses as blocked.
+- **1 or N MCP lanes**: every lane with an `mcpNamespace` (e.g. `mcp__playwright-qauser__`) adds its
+  15 Playwright MCP browser tools, in config order, plus a lane table and the mandatory
+  `lane-lock.js heartbeat` protocol. CLI-only lanes are skipped.
+- An invalid lane block or an `mcpNamespace` not matching `^mcp__[A-Za-z0-9_-]+__$` fails
+  `qa-investigador` only: the other five agents are still written and the command exits 1.
+  `qa-framework validate` reports the same problems.
+
+---
+
 ## CLI Reference
 
 ```

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.