@keber/qa-framework 1.5.2 → 1.6.1

package/agent-instructions/04b-test-stabilization.md

@@ -1,309 +0,0 @@
-# Agent Instructions: Test Stabilization
-
-> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-test-stabilization/SKILL.md`.
-> Kept as reference during the transition period. Do not update this file.
-
-**File**: `agent-instructions/04b-test-stabilization.md`  
-**Purpose**: Instructions for exhaustively reviewing and stabilizing generated Playwright tests to ensure they are logically correct, technically sound, and free of false positives and false negatives before ADO integration.
-
----
-
-## Stage Context
-
-| Field | Value |
-|-------|-------|
-| Stage number | 3.5 |
-| Stage name | Test Stabilization |
-| Preceding stage | Stage 4 — Automation Generation (`04-automation-generation.md`) |
-| Following stage | Stage 5 — ADO Integration (`05-ado-integration.md`) |
-| Can be skipped? | No — ADO integration with unreliable tests produces misleading test run history |
-| Required inputs | Generated `.spec.ts` files in `qa/07-automation/e2e/`; approved `05-test-scenarios.md` for the module |
-| Produced outputs | Stabilized spec files; `STABILIZATION-REPORT.md` per submodule |
-| Exit criterion | Confidence ≥ 90% that every test produces a true positive on failure and a true negative on pass |
-
----
-
-## When to use
-
-Run this stage immediately after **Stage 4 — Automation Generation** and before any ADO
-integration or CI pipeline registration. This stage is mandatory regardless of whether tests
-are passing or failing after generation.
-
-Also re-run this stage when:
-- Sprint changes introduce significant new test code (more than 3 new spec files)
-- A test suite starts flaking in CI after a previously stable period
-- A test is suspected of being a false positive (passing despite the feature being broken)
-- A test is suspected of being a false negative (failing despite the feature being correct)
-
----
-
-> **Scope boundary**: This stage operates exclusively on test code (`.spec.ts`, fixtures,
-> helpers, `global-setup.ts`, `playwright.config.ts`). The application source code is
-> strictly out of scope. Do not modify, patch, or work around application behavior to make
-> tests pass — document the mismatch as a defect instead.
-
----
-
-> **Coverage boundary**: Do not add new tests or increase coverage during this stage. If a
-> gap in coverage is identified, note it in the STABILIZATION-REPORT.md for Stage 6
-> (Maintenance) to address. The goal is correctness of existing tests, not completeness.
-
----
-
-## Step 1 — Establish the Reference Baseline
-
-Before running any tests, collect the ground truth against which correctness will be judged.
-
-1. Open `05-test-scenarios.md` for the target module/submodule. For each TC row, note:
-   - TC-ID and title
-   - Priority (P0/P1/P2/P3)
-   - Expected result (acceptance criterion)
-   - Automatable status (Yes / Partial / No)
-
-2. Open `COVERAGE-MAPPING.md` for the module. For each row:
-   - Confirm the `.spec.ts` file and test function name exist
-   - Flag any rows where the spec or function is missing (these are generation gaps, not
-     stabilization issues — document in the report but do not create new tests)
-
-3. If `05-test-scenarios.md` or `COVERAGE-MAPPING.md` are absent or incomplete, stop and
-   complete Stage 4 before proceeding.
-
----
-
-## Step 2 — First Run: Collect Baseline Results
-
-Run the full suite for the target module without any modifications:
-
-```bash
-npx playwright test qa/07-automation/e2e/tests/{module-kebab}/ --reporter=list
-```
-
-Record the outcome of every test:
-
-| TC-ID | Test title | Result | Notes |
-|-------|-----------|--------|-------|
-| TC-MOD-SUB-001 | ... | ✅ pass / ❌ fail / ⚠️ flaky / ⏭ skip | Error message if fail |
-
-Collect trace artifacts for every failing test:
-
-```bash
-npx playwright test ... --trace=on
-```
-
-Do NOT make any changes yet. The first run result is the diagnostic baseline.
-
----
-
-## Step 3 — Classify Every Failing or Skipped Test
-
-For each non-passing test, determine its failure category before writing any code.
-
-### Failure Categories
-
-| Category | Definition | Correct action |
-|----------|-----------|----------------|
-| **A — Test Bug: Wrong selector** | The selector no longer matches the UI element | Fix selector in `.spec.ts` |
-| **B — Test Bug: Wrong assertion** | The assertion does not match the specified acceptance criterion | Fix assertion to match spec |
-| **C — Test Bug: Wrong flow** | The test steps don't reflect the actual user flow described in the TC | Rewrite steps to match TC |
-| **D — Test Bug: Fragile timing** | Test fails intermittently due to missing `await`, race conditions, or missing `waitFor` | Add proper async handling |
-| **E — Test Bug: Incorrect data** | Test data is malformed, not unique, or conflicts with QA environment state | Fix data generation or provisioning |
-| **F — App Bug** | The test is correct and the application is not behaving as the TC specifies | Do not fix the test; file a defect |
-| **G — TC Mismatch** | The spec TC is ambiguous or incorrect vs the actual implemented behavior | Do not fix the test or the app; update `05-test-scenarios.md` and note as a spec defect |
-| **H — Infra / Environment** | Test fails due to QA environment unavailability, network, or credentials | Retry in a clean environment; do not classify as a test bug until confirmed |
-| **I — Intentional skip** | Test is marked `test.skip()` due to a known defect or pending feature | Verify skip reason is still valid; update `06-defects/open/` reference |
-
-For each failing test, write your classification in the working STABILIZATION-REPORT.md
-before making any change.
-
-### Decision Protocol
-
-```
-Is the test step sequence and assertion derived correctly from 05-test-scenarios.md?
-  No → Category G (TC Mismatch — fix the spec, not the test)
-  Yes ↓
-Does the application behave as the TC acceptance criterion describes?
-  No → Category F (App Bug — file a defect, skip the test with a DEF reference)
-  Yes ↓
-Does the failure appear in every run (deterministic)?
-  No → Category D or H (timing or environment — diagnose further)
-  Yes ↓
-Is the failure caused by a selector, assertion, data, or flow issue in the test code?
-  → Category A, B, C, or E (Test Bug — fix the test code)
-```
-
----
-
-## Step 4 — Fix Iterations
-
-Apply fixes one category at a time, in this order: E → A → C → B → D.
-(Data problems mask selector problems; flow problems mask assertion problems.)
-
-After each batch of fixes, re-run the affected tests:
-
-```bash
-npx playwright test qa/07-automation/e2e/tests/{module-kebab}/{file}.spec.ts --reporter=list
-```
-
-Do not move to the next category until the current category's tests are stable across
-**at least two consecutive runs**.
-
-### Rules for fixing test code
-
-- **Selectors**: prefer `getByRole`, `getByLabel`, `getByTestId` — avoid CSS/XPath selectors
-  that depend on position or class names that aren't semantic
-- **Assertions**: every assertion must trace back to a specific acceptance criterion in the TC;
-  remove or replace any `expect().toBeVisible()` that does not correspond to a TC requirement
-- **Waits**: prefer `await expect(locator).toBeVisible()` over `page.waitForTimeout()`;
-  never use `waitForTimeout` as a fix for timing — diagnose the actual cause
-- **Data**: use `EXEC_IDX + RUN_SALT` for unique identifiers (see ISSUE-02 note below);
-  provision data in `beforeAll`, not inside individual tests
-- **Skips**: when skipping for a Category F (App Bug), always include the defect reference:
-  ```typescript
-  test.skip(true, 'DEF-{NNN}: {one-line bug description}. Filed {YYYY-MM-DD}.');
-  ```
-
-> ⚠️ **EXEC_IDX collision**: Two runs within the same 60-second window produce identical
-> `EXEC_IDX` values. For fields requiring guaranteed uniqueness, add a salt:
-> ```typescript
-> const EXEC_IDX = Math.floor(Date.now() / 60_000) % 100_000;
-> const RUN_SALT = Math.floor(Math.random() * 9999).toString().padStart(4, '0');
-> ```
-
----
-
-## Step 5 — Validate Passing Tests for False Positives
-
-A passing test is not necessarily a correct test. After fixing failing tests, audit every
-**passing** test for false positives.
-
-For each passing test, perform one of the following checks:
-
-### Negation check (preferred)
-Temporarily modify the test to assert the opposite of the expected result, then run it.
-If it still passes — the test is a false positive (asserting nothing meaningful).
-
-```typescript
-// Original: expect(toast).toHaveText('Guardado exitosamente');
-// Negation check: replace temporarily with:
-expect(toast).toHaveText('TEXTO_QUE_NO_EXISTE_JAMAS');
-// If this passes → the original assertion is not actually evaluating the toast content
-```
-
-Restore the original assertion after the check.
-
-### Trace review (secondary)
-Open the Playwright trace for the passing test and step through it. Verify:
-- Every action in the `test()` body corresponds to a step in the TC
-- Every `expect()` is actually being evaluated (no skipped assertions due to early returns
-  or unreachable code)
-- The test does not pass because an early `expect()` short-circuits before the meaningful one
-
-### API/network verification (for tests touching data persistence)
-For tests that create, update, or delete records: after the UI action, verify the result
-is persisted, not just that a success toast appeared. A test that only checks the toast
-is a false positive if the actual save fails silently.
-
----
-
-## Step 6 — Iteration and Convergence
-
-Repeat Steps 4 and 5 until:
-
-1. All deterministic failures are resolved (either fixed or legitimately skipped with a
-   defect reference)
-2. All passing tests have passed the negation check or trace review
-3. No test produces intermittent results across 3 consecutive runs
-
-**Confidence scoring**: after each iteration, estimate confidence per test:
-
-| Confidence | Criteria |
-|-----------|---------|
-| ✅ High (≥90%) | Passed negation check AND matches TC acceptance criterion exactly |
-| ⚠️ Medium (70–89%) | Passes consistently; trace reviewed; no negation check yet |
-| ❌ Low (<70%) | Intermittent, unclassified failure, or negation check not attempted |
-
-The stage is complete when **all tests are ✅ High or legitimately skipped** (Category F
-with a defect reference or Category I with a valid skip reason).
-
----
-
-## Step 7 — Document Findings
-
-For each submodule, create or update `STABILIZATION-REPORT.md` in the module's automation
-directory:
-
-```
-qa/07-automation/e2e/tests/{module-kebab}/STABILIZATION-REPORT.md
-```
-
-### STABILIZATION-REPORT.md structure
-
-```markdown
-# Stabilization Report — {MODULE} > {SUBMODULE}
-
-**Date**: YYYY-MM-DD  
-**Sprint**: {sprint number or label}  
-**Analyst**: {agent session name or human name}  
-**Spec reference**: `qa/{module-key}/{submodule-key}/05-test-scenarios.md`
-
-## Summary
-
-| Metric | Value |
-|--------|-------|
-| Tests evaluated | N |
-| Tests stabilized (now ✅ High confidence) | N |
-| Tests skipped — App Bug (Category F) | N |
-| Tests skipped — Intentional (Category I) | N |
-| Remaining low-confidence tests | N |
-| Overall confidence | NN% |
-
-## Test-by-Test Record
-
-| TC-ID | Test title | Baseline result | Final result | Category | Changes made | Confidence |
-|-------|-----------|-----------------|-------------|----------|-------------|-----------|
-| TC-... | ... | ❌ fail | ✅ pass | A | Fixed selector `#old` → `getByRole('button', { name: '...' })` | ✅ High |
-
-## App Bugs Filed
-
-| DEF-ID | TC-ID | Description | Filed date | ADO WI (if created) |
-|--------|-------|-------------|-----------|---------------------|
-
-## Spec Defects (Category G)
-
-| TC-ID | Issue | Recommended `05-test-scenarios.md` update |
-|-------|-------|------------------------------------------|
-
-## Coverage Gaps Identified (do not fix in this stage)
-
-- {TC-ID}: test mapped in COVERAGE-MAPPING.md but `.spec.ts` function not found
-- ...
-
-## Decisions Log
-
-Chronological record of non-trivial decisions made during stabilization:
-
-- YYYY-MM-DD: Classified TC-XXX failure as Category F after verifying the save endpoint
-  returns 500 on duplicate RUTs. App bug, not test bug. DEF-001 filed.
-- ...
-```
-
----
-
-## Step 8 — Update Upstream Artifacts
-
-After completing STABILIZATION-REPORT.md:
-
-1. **If any Category G issues were found** (TC Mismatch): update `05-test-scenarios.md`
-   with the corrected acceptance criteria. Note the change with `[REVISED - {YYYY-MM-DD}]`.
-
-2. **If any Category F issues were found** (App Bug): create defect files in
-   `qa/{module-key}/{submodule-key}/06-defects/open/DEF-{NNN}.md` for each bug filed.
-
-3. **Update `COVERAGE-MAPPING.md`**: set the `Status` column for each TC:
-   - `Automated` — test is ✅ High confidence
-   - `Skipped-Defect` — test is skipped via `test.skip()` with a DEF reference
-   - `Skipped-Infra` — test is skipped due to environment limitation
-   - `Manual` — TC is intentionally not automated
-
-4. **Update session-summary.md** for the submodule: mark Stage 3.5 as ✅ Complete and
-   record the overall confidence percentage.

package/agent-instructions/05-ado-integration.md

@@ -1,247 +0,0 @@
-# Agent Instructions: Azure DevOps Integration
-
-> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-ado-integration/SKILL.md`.
-> Kept as reference during the transition period. Do not update this file.
-
-**File**: `agent-instructions/05-ado-integration.md`  
-**Purpose**: Instructions for an agent to create, configure, and maintain Azure DevOps Test Plans integration with Playwright automation results.
-
-> **This section is OPTIONAL**. Only use it when `integrations.azureDevOps.enabled = true` in `qa-framework.config.json`.
-
----
-
-## Prerequisites
-
-1. Azure DevOps PAT stored in `ADO_PAT` environment variable  
-   Required scopes: `Work Items (Read, Write)`, `Test Management (Read, Write)`
-2. `ADO_ORG` and `ADO_PROJECT` environment variables set
-3. PowerShell 5.1+ available
-4. `@alex_neo/playwright-azure-reporter` installed in the E2E package
-5. `qa/08-azure-integration/module-registry.json` exists with module paths and plan IDs
-
----
-
-## Step 1: Create ADO Test Plan
-
-If no Test Plan exists yet:
-
-```powershell
-# qa/08-azure-integration/scripts/create-testplan-from-mapping.ps1
-# Reads ado-ids-mapping-{project}.json and creates the plan + suites + TCs in ADO
-# Parameters: -Organization $env:ADO_ORG -Project $env:ADO_PROJECT -Token $env:ADO_PAT
-.\qa\08-azure-integration\scripts\create-testplan-from-mapping.ps1 `
-  -Organization $env:ADO_ORG `
-  -Project $env:ADO_PROJECT `
-  -Token $env:ADO_PAT `
-  -MappingFile .\qa\08-azure-integration\ado-ids-mapping-{project}.json
-```
-
-After running, the script outputs a `TestPlanId` and `SuiteIds`.  
-Record these in `qa/08-azure-integration/module-registry.json`.
-
----
-
-## Step 2: Inject ADO IDs into Spec Files
-
-Once Test Cases are created in ADO and have Work Item IDs:
-
-```powershell
-# Dry run first to preview changes
-.\qa\08-azure-integration\scripts\inject-ado-ids.ps1 `
-  -MappingFile .\qa\08-azure-integration\ado-ids-mapping-{project}.json `
-  -TestDir .\qa\07-automation\e2e\tests `
-  -DryRun
-
-# Apply changes
-.\qa\08-azure-integration\scripts\inject-ado-ids.ps1 `
-  -MappingFile .\qa\08-azure-integration\ado-ids-mapping-{project}.json `
-  -TestDir .\qa\07-automation\e2e\tests
-```
-
-This converts test titles from:
-```
-'[TC-OPER-CAT-001] Access catalog list @P0'
-```
-to:
-```
-'[22957] Access catalog list @P0'
-```
-
-Plus adds annotation:
-```typescript
-test.info().annotations.push({ type: 'TestCase', description: '22957' });
-```
-
----
-
-## Step 3: Configure playwright-azure-reporter
-
-In `playwright.config.ts`:
-
-```typescript
-import type { PlaywrightTestConfig } from '@playwright/test';
-
-const config: PlaywrightTestConfig = {
-  reporter: [
-    ['html'],
-    ['@alex_neo/playwright-azure-reporter', {
-      orgUrl: `https://dev.azure.com/${process.env.ADO_ORG}`,
-      token: process.env.ADO_PAT,
-      planId: Number(process.env.ADO_PLAN_ID),
-      projectName: process.env.ADO_PROJECT,
-      isDisabled: !process.env.CI,                    // only publish in CI
-      publishTestResultsMode: 'testRun',
-      testRunTitle: `QA Run - ${new Date().toISOString()}`,
-      uploadAttachments: true,
-      attachmentsType: ['screenshot', 'video', 'trace'],
-    }],
-  ],
-};
-export default config;
-```
-
-**Note**: Set `isDisabled: !process.env.CI` so the reporter only publishes from CI, not from local runs.
-
----
-
-## Step 4: Module Registry
-
-Maintain `qa/08-azure-integration/module-registry.json`:
-
-```json
-{
-  "modules": [
-    {
-      "name": "operacion",
-      "specsPath": "qa/07-automation/e2e/tests/operacion",
-      "planId": 0,
-      "suiteId": 0,
-      "description": "Módulo Operación — 7 submodules"
-    }
-  ]
-}
-```
-
-The CI pipeline uses this file to detect which module changed (via `git diff`) and run only the relevant spec.
-
----
-
-## Step 5: ADO IDs Mapping File
-
-Maintain `qa/08-azure-integration/ado-ids-mapping-{project}.json`:
-
-```json
-{
-  "planId": 22304,
-  "module": "operacion",
-  "specsPath": "qa/07-automation/e2e/tests/operacion",
-  "suites": [
-    {
-      "suiteId": 22956,
-      "suiteName": "Suite 1.1 - Catálogos de Trabajo",
-      "testCases": [
-        { "id": 22957, "title": "Access catalog list @P0", "tags": ["automatable", "playwright"] },
-        { "id": 22958, "title": "Create labor type @P1", "tags": ["automatable", "playwright"] }
-      ]
-    }
-  ]
-}
-```
-
----
-
-## Step 6: Configure CI Pipeline
-
-Template in `qa/08-azure-integration/pipelines/azure-pipeline-qa.yml`:
-
-```yaml
-trigger:
-  branches:
-    include:
-      - {{CI_TRIGGER_BRANCH}}
-
-pool:
-  vmImage: 'ubuntu-latest'
-
-variables:
-  - group: qa-secrets        # Must contain: QA_USER_EMAIL, QA_USER_PASSWORD, QA_BASE_URL, ADO_PAT
-
-steps:
-  - checkout: self
-    fetchDepth: 2
-
-  - task: NodeTool@0
-    inputs:
-      versionSpec: '20.x'
-    displayName: 'Install Node.js 20'
-
-  - script: |
-      cd qa/07-automation/e2e
-      npm install
-      npx playwright install chromium --with-deps
-    displayName: 'Install Playwright'
-
-  - script: |
-      cd qa/07-automation/e2e
-      npx playwright test
-    displayName: 'Run Playwright tests'
-    env:
-      QA_BASE_URL: $(QA_BASE_URL)
-      QA_USER_EMAIL: $(QA_USER_EMAIL)
-      QA_USER_PASSWORD: $(QA_USER_PASSWORD)
-      ADO_PAT: $(ADO_PAT)
-      ADO_PLAN_ID: $(ADO_PLAN_ID)
-      CI: 'true'
-
-  - task: PublishTestResults@2
-    inputs:
-      testResultsFormat: 'JUnit'
-      testResultsFiles: '**/test-results/*.xml'
-    displayName: 'Publish JUnit results'
-    condition: always()
-
-  - task: PublishPipelineArtifact@1
-    inputs:
-      targetPath: 'qa/07-automation/e2e/playwright-report'
-      artifact: 'playwright-html-report'
-    displayName: 'Publish HTML report'
-    condition: always()
-```
-
----
-
-## Syncing ADO TC Titles with Spec Titles
-
-If TC titles drift between ADO and the spec files:
-
-```powershell
-.\qa\08-azure-integration\scripts\sync-ado-titles.ps1 `
-  -Organization $env:ADO_ORG `
-  -Project $env:ADO_PROJECT `
-  -Token $env:ADO_PAT `
-  -MappingFile .\qa\08-azure-integration\ado-ids-mapping-{project}.json `
-  -DryRun
-```
-
-This reads ADO TC titles and compares them against the spec. Outputs a diff report. Apply with `-DryRun:$false`.
-
----
-
-## Credential Security Rules for ADO
-
-1. `ADO_PAT` is **never** committed to any file — always comes from env var or CI variable group
-2. `ADO_PAT` is **never** logged, printed, or written to any markdown file
-3. If a PAT appears in any log or output, revoke it immediately in ADO Portal and generate a new one
-4. Variable group `qa-secrets` in Azure DevOps must be scoped to the pipeline only
-5. PAT minimum scopes: `Work Items (Read, Write)`, `Test Management (Read, Write)` — do not use full access PATs
-
----
-
-## Troubleshooting
-
-| Symptom | Likely Cause | Fix |
-|---------|-------------|-----|
-| Reporter silently does nothing in CI | `isDisabled: true` or `CI` env not set | Verify `process.env.CI` is `'true'` in pipeline |
-| Tests report as "Not Run" in ADO | ADO WI ID not in test title or annotation | Re-run `inject-ado-ids.ps1` |
-| TestRun created but no results attached | `publishTestResultsMode` wrong | Use `'testRun'` not `'testCase'` |
-| PAT error 401 | PAT expired or wrong scopes | Generate new PAT with correct scopes |

package/agent-instructions/06-maintenance.md

@@ -1,135 +0,0 @@
-# Agent Instructions: Maintenance and Updates
-
-> ⚠️ **DEPRECATED**: This file is superseded by `.github/skills/qa-maintenance/SKILL.md`.
-> Kept as reference during the transition period. Do not update this file.
-
-**File**: `agent-instructions/06-maintenance.md`  
-**Purpose**: Instructions for updating QA artifacts after application code changes.
-
----
-
-## When to use
-
-- A developer reports a feature change or new feature in a module
-- A sprint delivers changes to an already-analyzed module
-- A defect is resolved and related `test.skip()` calls need to be reactivated
-- The QA environment is updated and existing specs need to be refreshed
-
----
-
-## Step 1: Identify What Changed
-
-Gather from the developer or ticket:
-- Which module/submodule was changed?
-- Was it a new feature, a modification, or a bug fix?
-- Are there new routes, fields, or API endpoints?
-- Were any existing behaviors removed or changed?
-
-If the change scope is unclear, navigate to the affected module in the QA environment and compare against the existing `00-inventory.md`.
-
----
-
-## Step 2: Spec Update Rules
-
-### A new field was added to a form
-
-1. Add the field to `00-inventory.md` under UI Elements table
-2. If the field has validation: add a business rule to `01-business-rules.md` (`RN-{MODULE}-{next-number}`)
-3. Add TCs to `05-test-scenarios.md`:
-   - TC for happy path with the new field
-   - TC for required validation (if applicable)
-   - TC for any new business rule
-
-### A field was removed from the UI
-
-1. Mark the field in `00-inventory.md` as `[REMOVED - {YYYY-MM-DD}]` — do not delete the row
-2. If automation tests reference the field selector: update or skip them
-3. If a business rule only applied to that field: mark as `[DEPRECATED - {YYYY-MM-DD}]`
-4. Leave TCs in `05-test-scenarios.md` marked as `[DEPRECATED]` for traceability
-
-### A workflow was changed
-
-1. Update `02-workflows.md` with the new flow
-2. Mark the old version as `[PREVIOUS - {YYYY-MM-DD}]`
-3. Review all TCs that test the affected steps
-4. Update expected results in `05-test-scenarios.md`
-
-### A new submodule was added
-
-Follow the full module analysis process in `00-module-analysis.md`.
-
-### A defect was fixed
-
-1. Find all `test.skip()` calls that reference the DEF-ID or ADO WI
-2. Remove the `test.skip()` wrapper
-3. Run the test at least 2 times with different EXEC_IDX values to confirm stability
-4. Update `06-defects/DEF-{NNN}.md` (or ADO WI) status to Resolved
-5. If the spec assertion was adapted to document the bug (e.g., `toBeFalsy()` for a wrong default), restore the correct assertion
-
----
-
-## Step 3: Automation Update Rules
-
-### Selectors changed (redesign, framework update)
-
-1. Locate the POM file or spec file that contains the old selector
-2. Check `CORRECTIONS` block at top of spec file (convention for documenting selector audits)
-3. Update the selector
-4. Run the affected test 2+ times to confirm the new selector is stable
-5. Add an entry to the `CORRECTIONS` block noting the change and date
-
-### New test suite needed
-
-Follow `04-automation-generation.md` for the new suite.  
-Update `COVERAGE-MAPPING.md` with the new TCs.
-
-### Test became flaky after app update
-
-Use the 5-layer debugging methodology:
-1. Environment: is QA env stable?
-2. Timeout: did an operation become slower?
-3. Data: did a seed or precondition change?
-4. Selector: did the element structure change?
-5. System: is this a real defect?
-
----
-
-## Step 4: Version the Spec
-
-At the bottom of each updated spec file, add to the changelog:
-
-```markdown
-## Changelog
-
-| Version | Date | Description |
-|---------|------|-------------|
-| 1.0 | YYYY-MM-DD | Initial creation |
-| 1.1 | YYYY-MM-DD | Added RN-{MODULE}-{NNN}: {rule title}. TC count: N → M |
-| 1.2 | YYYY-MM-DD | Removed field {name} from UI inventory (deprecated) |
-```
-
----
-
-## Step 5: Update qa/README.md
-
-After every maintenance session, update the master index:
-- TC count (if changed)
-- Automation status (if changed)
-- Last updated date for the module
-
-If a **sprint was fully completed** as part of this maintenance pass (all TCs passing after the changes):
-1. Move the completed sprint checklist from `AGENT-NEXT-STEPS.md` to the `## Sprint History` section of `qa/README.md`
-2. Delete the completed sprint block from `AGENT-NEXT-STEPS.md`
-3. Confirm `AGENT-NEXT-STEPS.md` contains **only one active sprint** — never let it accumulate history
-
-Also update `qa/memory/INDEX.md` if any memory files were created or modified.
-
----
-
-## Step 6: Write a Session Summary
-
-Create `qa/SESSION-SUMMARY-{YYYY-MM-DD}-maintenance.md` documenting:
-- What changed
-- Which files were updated
-- Any new TCs or deprecated TCs
-- Any tests that were reactivated or newly skipped