@keber/qa-framework 1.11.3 → 1.13.0

package/skills/qa-automation/references/pom-template.md

@@ -0,0 +1,161 @@
+# Reference: Page Object Template
+
+> Loaded by `skills/qa-automation/` at Step 1b, when the POM decision criteria are met.
+
+A Page Object owns **locators and interactions** for one submodule. It never owns assertions about
+business rules - those belong in the spec file, where they can be traced to a TC ID.
+
+---
+
+## Two-layer structure
+
+Most modules end up with the same shape: one abstract base per module holding the CRUD interaction
+vocabulary shared by every submodule, and one thin concrete class per submodule holding only its
+route, its identity, and whatever it genuinely does differently.
+
+```
+page-objects/
+  {module}/
+    Base{MODULE}CRUDPage.ts     <- shared interactions, abstract
+    {MODULE}{Sub}Page.ts         <- route + submodule-specific overrides only
+```
+
+Write the concrete class first with inline locators. Promote a method to the base class on the
+**second** submodule that needs it, not in anticipation of the first.
+
+---
+
+## Base class template
+
+```typescript
+import { Page, Locator } from '@playwright/test';
+import { expect } from '../../fixtures/base';
+
+/**
+ * Shared CRUD interactions for {MODULE} submodules.
+ *
+ * Locators here must match the UI framework the app actually renders. Confirm them
+ * against a real DOM inspection (Step 0) before writing tests - never from assumption.
+ */
+export abstract class Base{MODULE}CRUDPage {
+  readonly page: Page;
+
+  constructor(page: Page) {
+    this.page = page;
+  }
+
+  async navigateTo(route: string): Promise<void> {
+    await this.page.goto(route);
+    await this.page.waitForLoadState('domcontentloaded');
+  }
+
+  async waitForGrid(): Promise<void> {
+    await this.page.locator('{GRID_ROW_SELECTOR}').first().waitFor({ timeout: 20_000 });
+  }
+
+  // Label-driven field access. See "Accent-insensitive label matching" below before
+  // writing this for a Spanish-language UI.
+  fieldInput(label: string): Locator {
+    return this.page.getByLabel(label);
+  }
+
+  async fillField(label: string, value: string): Promise<void> {
+    await this.fieldInput(label).fill(value);
+  }
+
+  async clickNuevoRegistro(): Promise<void> {
+    await this.page.getByRole('button', { name: /{CREATE_BUTTON_PATTERN}/i }).click();
+  }
+
+  async clickGuardar(): Promise<void> {
+    await this.page.getByRole('button', { name: /{SAVE_BUTTON_PATTERN}/i }).click();
+  }
+
+  async verifyValidationError(fieldLabel: string): Promise<void> {
+    await expect(
+      this.fieldInput(fieldLabel).locator('{VALIDATION_MESSAGE_SELECTOR}')
+    ).toBeVisible({ timeout: 5_000 });
+  }
+
+  async verifyRowInGrid(text: string | RegExp): Promise<void> {
+    await expect(this.page.locator('{GRID_ROW_SELECTOR}').filter({ hasText: text }))
+      .toBeVisible();
+  }
+}
+```
+
+---
+
+## Concrete submodule template
+
+```typescript
+import { Page } from '@playwright/test';
+import { Base{MODULE}CRUDPage } from './Base{MODULE}CRUDPage';
+
+// {SUBMODULE_CODE}: {display name} ({route})
+// Fields: {field} (required), {field} (auto/read-only), ...
+// Known defects affecting this submodule: {DEF-ID}: {one-line description}
+export class {MODULE}{Sub}Page extends Base{MODULE}CRUDPage {
+  static readonly route = '{route}';
+  static readonly submoduleCode = '{SUBMODULE_CODE}';
+  static readonly displayName = '{display name}';
+
+  constructor(page: Page) {
+    super(page);
+  }
+
+  // Only what this submodule does differently. If a second submodule needs this
+  // method, move it to the base class then - not before.
+}
+```
+
+The three `static readonly` fields let a spec file reference the submodule without duplicating
+string literals, and make the POM self-describing when read on its own.
+
+---
+
+## Accent-insensitive label matching (Spanish-language UIs)
+
+**This is a measured failure mode, not a precaution.** In one project, 24 of 39 CAT smoke tests
+failed because the specs were written with unaccented Spanish labels (`Codigo`, `Compania naviera`,
+`Tipo de emision`) while the DOM renders the correct accents (`Código`, `Compañía naviera`,
+`Tipo de emisión`). An exact-text selector never matches. Two unrelated mitigations were attempted
+first - raising the grid timeout and forcing HTTP/1.1 - because the failure presents as a timeout,
+not as a text mismatch.
+
+The durable fix is to write specs with correct accents in the first place (they describe a Spanish
+UI, so they must carry Spanish orthography). Where a base class must tolerate both, match the
+whole label accent-insensitively:
+
+```typescript
+// Anchored with ^...$ on purpose: unanchored, :text-matches() matches as a SUBSTRING of the
+// element's full text, so a short label can match several elements and trip strict mode.
+accentInsensitiveRegex(text: string): RegExp {
+  const accentClass: Record<string, string> = {
+    a: 'aá', e: 'eé', i: 'ií', o: 'oó', u: 'uúü', n: 'nñ',
+  };
+  const escaped = text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = escaped.replace(/[aeioun]/gi, (ch) => {
+    const cls = accentClass[ch.toLowerCase()];
+    return cls ? `[${cls}]` : ch;
+  });
+  return new RegExp(`^${pattern}$`, 'i');
+}
+```
+
+Apply it in **every** label-driven method - field inputs, validation messages, and foreign-key
+selectors alike. In the project above, only two of the three families were overridden on the first
+pass, and the FK selectors kept failing for another two days until the same fix reached them.
+
+---
+
+## Rules
+
+| Rule | Correct | Wrong |
+|---|---|---|
+| Assertions | Business assertions live in the spec, traced to a TC ID | POM asserts business rules |
+| Locators | Confirmed against a real DOM inspection (Step 0) | Guessed from the spec's prose |
+| Waiting | `waitFor` on a state or a response | `waitForTimeout` |
+| Promotion to base | On the second submodule that needs it | Anticipated on the first |
+| Credentials | Fixture-provided | Referenced inside the POM |
+| Header comment | Records inspection date, fields, known defects | Undocumented selectors |

package/skills/qa-maintenance/SKILL.md

@@ -11,10 +11,10 @@ description: >
 
 # QA Skill: Maintenance (Stage 6 of 6)
 
-**Stage**: 6 — Maintenance  
+**Stage**: 6 - Maintenance  
 **Prerequisite**: An application change (bug fix, feature change, new requirement) has been delivered  
 **Output**: Updated specs, TCs, and automation aligned with the new application behavior  
-**Cycle**: Returns to Stage 2 (spec update) → Stage 4 (TC update) → Stage 5 (automation update) as needed
+**Cycle**: Returns to Stage 2 (spec update) -> Stage 4 (TC update) -> Stage 5 (automation update) as needed
 
 > **Rule**: Never update specs to match an incorrect application behavior. Specs define correct behavior; automation reflects specs. If the app is wrong, file a defect, don't update the spec.
 
@@ -22,16 +22,16 @@ description: >
 
 ## Inputs Required
 
-1. Description of the change — which submodule, what changed, and why
-2. `qa/01-specifications/{module}/` — specs affected by the change
-3. `qa/07-automation/e2e/tests/{module}/` — automation affected by the change
+1. Description of the change - which submodule, what changed, and why
+2. `qa/01-specifications/{module}/` - specs affected by the change
+3. `qa/07-automation/e2e/tests/{module}/` - automation affected by the change
 4. Optionally: ADO work item or defect report describing the change
 
 ---
 
 ## Process
 
-### Step 1 — Identify affected artifacts
+### Step 1 - Identify affected artifacts
 
 For the delivered change, identify:
 - Which spec files reference the changed behavior (search for affected term/field/flow)
@@ -39,7 +39,7 @@ For the delivered change, identify:
 - Which automation files implement those TCs
 - Whether any test data in `04-test-data.md` is affected
 
-### Step 2 — Update specs first
+### Step 2 - Update specs first
 
 Update spec files before touching automation. Spec update rules:
 
@@ -54,14 +54,14 @@ Update spec files before touching automation. Spec update rules:
 
 Detailed rules: `references/update-rules.md`
 
-### Step 3 — Update TCs
+### Step 3 - Update TCs
 
 After specs are updated:
 - Update step text in affected `TC-*.md` files
 - If a TC no longer applies: mark as `[OBSOLETE]` in the index, do not delete the file
 - If a new scenario added to specs: generate new TC following Stage 4
 
-### Step 4 — Update automation
+### Step 4 - Update automation
 
 After TCs are updated:
 - Update locators for changed UI elements
@@ -71,7 +71,7 @@ After TCs are updated:
 
 Automation update rules: `references/update-rules.md`
 
-### Step 5 — Bump spec version and log change
+### Step 5 - Bump spec version and log change
 
 In the spec file's YAML frontmatter (or header block):
 ```
@@ -80,7 +80,7 @@ last-updated: {date}
 change-summary: {one-line description of what changed}
 ```
 
-### Step 6 — Update README and close session
+### Step 6 - Update README and close session
 
 - Update `qa/README.md` module row (spec version, TC count if changed, automation status)
 - Update `AGENT-NEXT-STEPS.md`:

package/skills/qa-maintenance/references/update-rules.md

@@ -17,7 +17,7 @@
 
 ### Field removed from UI
 
-1. Mark row in `00-inventory.md` as `[REMOVED - {YYYY-MM-DD}]` — do NOT delete the row
+1. Mark row in `00-inventory.md` as `[REMOVED - {YYYY-MM-DD}]` - do NOT delete the row
 2. Mark the related business rule in `01-business-rules.md` as `[DEPRECATED - {YYYY-MM-DD}]`
 3. Mark related TCs in `05-test-scenarios.md` as `[DEPRECATED]` for traceability
 4. Update or skip automation tests that reference the removed element's selector
@@ -26,7 +26,7 @@
 
 1. Update `02-workflows.md` with the new flow diagram
 2. Mark the old version as `[PREVIOUS - {YYYY-MM-DD}]` inside the same file (keep for reference)
-3. Review all TCs that test the affected steps — update expected results in `05-test-scenarios.md`
+3. Review all TCs that test the affected steps - update expected results in `05-test-scenarios.md`
 
 ### New submodule added
 
@@ -47,7 +47,7 @@ Follow the full module analysis process: `skills/qa-module-analysis/`.
 ### Selectors changed (redesign or framework update)
 
 1. Locate the spec file or page object containing the old selector
-2. Update the selector — prefer `getByRole`, `getByLabel`, `getByTestId`
+2. Update the selector - prefer `getByRole`, `getByLabel`, `getByTestId`
 3. Run the affected test 2+ times to confirm stability
 4. Add an entry to the correction log at top of the spec file:
 
@@ -83,7 +83,7 @@ Add to the bottom of each updated spec file:
 | 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.1 | YYYY-MM-DD | Added RN-{MODULE}-{NNN}: {rule title}. TC count: N -> M |
 | 1.2 | YYYY-MM-DD | Removed field {name} (deprecated) |
 ```
 
@@ -94,7 +94,7 @@ Add to the bottom of each updated spec file:
 Create at: `qa/SESSION-SUMMARY-{YYYY-MM-DD}-maintenance.md`
 
 ```markdown
-# Maintenance Session — {YYYY-MM-DD}
+# Maintenance Session - {YYYY-MM-DD}
 
 ## Change trigger
 {Brief description of the application change that triggered this session}
@@ -108,11 +108,11 @@ Create at: `qa/SESSION-SUMMARY-{YYYY-MM-DD}-maintenance.md`
 ## TC changes
 - New TCs: {IDs} (+N total)
 - Deprecated TCs: {IDs} (-N total)
-- Net TC count: {module} → {N}
+- Net TC count: {module} -> {N}
 
 ## Tests reactivated
-- {TC-ID}: removed test.skip() — DEF-{NNN} resolved
+- {TC-ID}: removed test.skip() - DEF-{NNN} resolved
 
 ## Tests newly skipped
-- {TC-ID}: test.skip() added — DEF-{NNN} filed for {bug description}
+- {TC-ID}: test.skip() added - DEF-{NNN} filed for {bug description}
 ```

package/skills/qa-module-analysis/SKILL.md

@@ -10,10 +10,10 @@ description: >
 
 # QA Skill: Module Analysis (Stage 1 of 6)
 
-**Stage**: 1 — Module Analysis  
-**Prerequisite**: None — this is the first stage  
+**Stage**: 1 - Module Analysis  
+**Prerequisite**: None - this is the first stage  
 **Output**: `qa/01-specifications/module-{name}/submodule-{name}/` with 6 spec files  
-**Next stage**: Stage 2 — Specification Generation (`qa-spec-generation`)
+**Next stage**: Stage 2 - Specification Generation (`qa-spec-generation`)
 
 > **Pipeline rule**: This stage must be completed before any spec generation, test planning,
 > or automation can begin. Do not skip to a later stage.
@@ -33,32 +33,32 @@ Before starting:
 
 ---
 
-## Phase 1 — Preparation
+## Phase 1 - Preparation
 
 1. Check if `qa/01-specifications/module-{name}/` already exists
    - **Exists**: read all existing files; only re-analyze what changed
    - **New**: create the directory and plan submodules
-2. Allocate a unique 2–6 letter uppercase module code (check naming-conventions.md for conflicts)
+2. Allocate a unique 2-6 letter uppercase module code (check naming-conventions.md for conflicts)
 3. Create `qa/01-specifications/module-{name}/README.md` listing all planned submodules before analysis begins
 
 ---
 
-## Phase 2 — Exploration (one pass per submodule)
+## Phase 2 - Exploration (one pass per submodule)
 
 For each submodule, use browser automation to collect:
 
-1. **Navigation** — URLs, page titles, breadcrumbs
-2. **UI inventory** — all inputs (type, required, validation), dropdowns (options), buttons, tables, modals, badges
-3. **API endpoints** — observe network requests during create/read/update/delete; record method, path, payload shape
-4. **Role access** — log in as each configured role; record `can access / cannot access / permission error`
-5. **Workflow** — execute the primary happy path; record steps, branch points, state transitions
-6. **Business rules** — attempt invalid inputs and boundary conditions; record validation messages exactly
+1. **Navigation** - URLs, page titles, breadcrumbs
+2. **UI inventory** - all inputs (type, required, validation), dropdowns (options), buttons, tables, modals, badges
+3. **API endpoints** - observe network requests during create/read/update/delete; record method, path, payload shape
+4. **Role access** - log in as each configured role; record `can access / cannot access / permission error`
+5. **Workflow** - execute the primary happy path; record steps, branch points, state transitions
+6. **Business rules** - attempt invalid inputs and boundary conditions; record validation messages exactly
 
 Detailed exploration checklist: `references/exploration-checklist.md`
 
 ---
 
-## Phase 3 — Documentation (6-file output)
+## Phase 3 - Documentation (6-file output)
 
 Produce 6 files per submodule. File formats and templates: `references/spec-file-formats.md`
 
@@ -69,13 +69,13 @@ Produce 6 files per submodule. File formats and templates: `references/spec-file
 | `02-workflows.md` | `FL-{MODULE}-{NNN}` flows with ASCII/Mermaid diagrams |
 | `03-roles-permissions.md` | Role × feature access matrix; env var references for test users |
 | `04-test-data.md` | Prerequisites, data shapes per scenario, EXEC_IDX pattern |
-| `05-test-scenarios.md` | TC table: 50–85 TCs per submodule, all mandatory coverage categories |
+| `05-test-scenarios.md` | TC table: 50-85 TCs per submodule, all mandatory coverage categories |
 
-TC target: **50–85 per submodule**. Mark origin as `UI-OBSERVED`, `PENDING-CODE`, or `BLOCKED-PERMISSIONS`.
+TC target: **50-85 per submodule**. Mark origin as `UI-OBSERVED` (element and behavior both confirmed this session), `PENDING-BROWSER` (element observed but the behavior could not be exercised end-to-end this session, e.g. a disabled control or an unmet precondition), `PENDING-CODE` (feature not present or not reachable in this environment), or `BLOCKED-PERMISSIONS` (blocked by role/access, not by feature absence).
 
 ---
 
-## Phase 4 — Review
+## Phase 4 - Review
 
 Completeness checklist before closing the stage:
 
@@ -85,11 +85,12 @@ Completeness checklist before closing the stage:
 - [ ] All TC IDs are unique across the module
 - [ ] Module README updated with submodule table and TC counts
 - [ ] `qa/README.md` module status row updated
+- [ ] Output verification run and the counts reported (see `references/output-verification.md`) - report the command output, never a compliance claim
 
 ---
 
 ## Outputs
 
-- `qa/01-specifications/module-{name}/` — fully populated spec tree
-- `qa/01-specifications/module-{name}/README.md` — updated with submodule table
-- `qa/README.md` — module status row updated
+- `qa/01-specifications/module-{name}/` - fully populated spec tree
+- `qa/01-specifications/module-{name}/README.md` - updated with submodule table
+- `qa/README.md` - module status row updated

package/skills/qa-module-analysis/references/exploration-checklist.md

@@ -63,9 +63,9 @@ For each configured test user role:
 
 ```
 Execute the primary happy path with appropriate test data
-Record each step (clickable element → navigation result → system state change)
+Record each step (clickable element -> navigation result -> system state change)
 Identify branch points (e.g., approve vs reject)
-Record state transitions (pending → approved → rejected)
+Record state transitions (pending -> approved -> rejected)
 ```
 
 ---
@@ -100,7 +100,7 @@ After completing all submodule files:
 ## Session Summary Template
 
 ```markdown
-# Session Summary — {YYYY-MM-DD}
+# Session Summary - {YYYY-MM-DD}
 
 ## Module analyzed
 {module-name} ({module-code})
@@ -114,7 +114,7 @@ After completing all submodule files:
 - {path/to/file.md}
 
 ## Blockers
-- {any features marked PENDING-CODE or BLOCKED-PERMISSIONS}
+- {any features marked PENDING-CODE, PENDING-BROWSER, or BLOCKED-PERMISSIONS}
 
 ## Next steps
 - {what remains before automation can begin}

package/skills/qa-module-analysis/references/output-verification.md

@@ -0,0 +1,69 @@
+# Reference: Output Verification (measure, do not assert)
+
+> Shared by every skill that generates documentation: `qa-module-analysis`, `qa-spec-generation`,
+> `qa-test-plan`, `qa-test-cases`.
+
+A compliance claim is not evidence. When a stage ends, report the **command output** that proves the
+artifact is correct - never the sentence "it complies".
+
+This exists because the failure it prevents is measured, not hypothetical. In one project a
+sub-agent wrote 5 memory files, 5 index rows and a task section entirely without Spanish accents,
+then reported explicitly that it had complied with the accent rule - the rule having been passed to
+it in full. The defect was caught only because the orchestrator ran the count by hand. Asked for the
+count instead of the claim, the same agent produced the real numbers and corrected itself.
+
+---
+
+## Run before closing any stage that wrote a `.md`
+
+Replace `<file>` with each file the stage created or modified.
+
+```bash
+# 1. Spanish orthography - accented characters must be present in Spanish prose.
+#    A Spanish document scoring 0 is defective, not stylistically different.
+rg -c '[áéíóúÁÉÍÓÚñÑüÜ]' <file>
+
+# 2. Forbidden characters - must return nothing.
+#    em-dash, en-dash, ellipsis, smart quotes, arrows.
+rg -n $'[\u2013\u2014\u2018\u2019\u201c\u201d\u2026\u2190-\u21ff]' <file>
+
+# 3. No BOM - must not print EF BB BF.
+head -c3 <file> | od -An -tx1
+```
+
+Report the actual numbers per file. If a count is missing, the stage is not closed.
+
+Check 1 is also available as a script that classifies the file's language first, so English
+artifacts are not asked for accents they should not have:
+
+```bash
+node node_modules/@keber/qa-framework/scripts/check-spanish-accents.js <file|dir>
+node node_modules/@keber/qa-framework/scripts/check-spanish-accents.js --staged   # pre-commit
+node node_modules/@keber/qa-framework/scripts/check-spanish-accents.js --report <paths>
+```
+
+It exits 1 when a Spanish file has no accented characters. Wire the `--staged` form into a
+pre-commit hook to make the rule a control rather than an expectation.
+
+---
+
+## Why the accent check is not cosmetic
+
+Specs written without accents propagate into automation. Page objects locate fields by their visible
+label, so a spec that says `Codigo` while the UI renders `Código` produces a selector that never
+matches. In one project this caused 24 of 39 smoke tests to fail, and cost two wrong mitigations
+(raising a timeout, forcing HTTP/1.1) before the real cause was found - because the failure presents
+as a timeout, not as a text mismatch. See `skills/qa-automation/references/pom-template.md`.
+
+Write the accents at the source. Every downstream stage inherits them.
+
+---
+
+## Language boundary
+
+Spanish artifacts (specs, plans, test cases, reports, defect files) must carry Spanish orthography.
+
+Artifacts that are legitimately English - the framework's own skill files, English documentation -
+score `0` on check 1 and that is correct. Never fabricate Spanish prose to satisfy the metric; report
+the language of the artifact and move on. The check applies to content that **is** Spanish, and
+`conventions.language` in `qa/qa-framework.config.json` says which that is.

package/skills/qa-module-analysis/references/spec-file-formats.md

@@ -8,7 +8,7 @@
 ## `00-inventory.md`
 
 ```markdown
-# MODULE: {Module Display Name} — Submodule: {Submodule Display Name}
+# MODULE: {Module Display Name} - Submodule: {Submodule Display Name}
 
 | Field | Value |
 |-------|-------|
@@ -47,11 +47,11 @@
 ```
 
 **Rule identification tips**:
-- Every required field → at least 1 RN
-- Every unique constraint → 1 RN (duplicate not allowed)
-- Every state transition → 1 RN (can only approve if status=pending)
-- Every role restriction → 1 RN
-- Every auto-calculated field → 1 RN
+- Every required field -> at least 1 RN
+- Every unique constraint -> 1 RN (duplicate not allowed)
+- Every state transition -> 1 RN (can only approve if status=pending)
+- Every role restriction -> 1 RN
+- Every auto-calculated field -> 1 RN
 
 ---
 
@@ -88,7 +88,7 @@
 ## `03-roles-permissions.md`
 
 ```markdown
-# Roles and Permissions — {Submodule}
+# Roles and Permissions - {Submodule}
 
 ## Access Matrix
 
@@ -115,7 +115,7 @@
 ## `04-test-data.md`
 
 ```markdown
-# Test Data — {Submodule}
+# Test Data - {Submodule}
 
 ## Prerequisites
 
@@ -129,7 +129,7 @@
 - Field A: {value type}
 - User: role `{ROLE_NAME}`, credentials from `QA_USER_{ROLE}_EMAIL` env var
 
-### Scenario: {negative — duplicate}
+### Scenario: {negative - duplicate}
 - Precondition: {entity} with the same key already exists
 - Field A: {same value as existing record}
 - Expected: {system rejection behavior}
@@ -153,7 +153,7 @@ const uniqueTitle = `Test-${EXEC_IDX}`;
 ## `05-test-scenarios.md`
 
 ```markdown
-# Test Scenarios — {Module}: {Submodule}
+# Test Scenarios - {Module}: {Submodule}
 
 **Module code**: {MODULE_CODE}  
 **Submodule code**: {SUBMODULE_CODE}  
@@ -177,7 +177,7 @@ const uniqueTitle = `Test-${EXEC_IDX}`;
 |-------|-------|
 | Priority | P0 / P1 / P2 / P3 |
 | Type | Functional / Negative / Regression / Security / Integration |
-| Origin | UI-OBSERVED / PENDING-CODE / BLOCKED-PERMISSIONS |
+| Origin | UI-OBSERVED / PENDING-BROWSER / PENDING-CODE / BLOCKED-PERMISSIONS |
 | Automation | Yes / Partial / No |
 | Playwright | (fill after automation is written) |
 
@@ -199,9 +199,9 @@ const uniqueTitle = `Test-${EXEC_IDX}`;
 - [ ] Access: unauthenticated user redirected to login
 - [ ] Access: role without permission receives error or empty page
 - [ ] Happy path: primary workflow with valid data succeeds
-- [ ] Negative: required field missing → validation error shown
-- [ ] Negative: duplicate record → system rejects with error message
-- [ ] Negative: invalid format → format error shown
+- [ ] Negative: required field missing -> validation error shown
+- [ ] Negative: duplicate record -> system rejects with error message
+- [ ] Negative: invalid format -> format error shown
 - [ ] State transition: state changes correctly on action
 - [ ] Export/download: file is generated (if feature exists)
 - [ ] Pagination/search: filtering works correctly (if feature exists)

package/skills/qa-spec-generation/SKILL.md

@@ -10,10 +10,10 @@ description: >
 
 # QA Skill: Specification Generation (Stage 2 of 6)
 
-**Stage**: 2 — Specification Generation  
+**Stage**: 2 - Specification Generation  
 **Prerequisite**: `00-inventory.md` must exist (Stage 1 complete)  
 **Output**: Complete 6-file spec set under `qa/01-specifications/module-{name}/submodule-{name}/`  
-**Next stage**: Stage 3 — Test Plan (`qa-test-plan`)
+**Next stage**: Stage 3 - Test Plan (`qa-test-plan`)
 
 > **Pipeline rule**: Do not generate specs for features marked `PENDING-CODE` in the inventory.
 > Do not create TCs without having observed or been given the behavior being tested.
@@ -31,7 +31,7 @@ description: >
 
 ## File Generation Rules
 
-Generate or update each file following the formats in `references/spec-file-formats.md`.
+Generate or update each file following the formats in `../qa-module-analysis/references/spec-file-formats.md` (shared reference, not duplicated per skill).
 
 ### `00-inventory.md`
 - Header block: module/submodule codes, primary URL, status, last updated date
@@ -41,8 +41,8 @@ Generate or update each file following the formats in `references/spec-file-form
 
 ### `01-business-rules.md`
 - Format: `RN-{MODULE}-{NNN}` with type, trigger, behavior, error message (exact UI text)
-- **Rule sources**: every required field → 1 RN; every unique constraint → 1 RN; every state transition → 1 RN; every role restriction → 1 RN
-- Minimum 5 rules per submodule; typical 8–15
+- **Rule sources**: every required field -> 1 RN; every unique constraint -> 1 RN; every state transition -> 1 RN; every role restriction -> 1 RN
+- Minimum 5 rules per submodule; typical 8-15
 
 ### `02-workflows.md`
 - Format: `FL-{MODULE}-{NNN}` with actor, trigger, precondition, ASCII/Mermaid flow diagram, postcondition
@@ -61,7 +61,7 @@ Generate or update each file following the formats in `references/spec-file-form
 ### `05-test-scenarios.md`
 - Summary table at top (total TCs by priority and type)
 - TC format: `TC-{MODULE}-{SUBMODULE}-{NNN}` with priority, type, origin, automation feasibility, preconditions, steps, expected result
-- **Target**: 50–85 TCs per submodule
+- **Target**: 50-85 TCs per submodule
 - **Mandatory coverage categories** (≥1 TC each where applicable):
   - Access: unauthenticated user; role without permission
   - Happy path: primary workflow end-to-end
@@ -70,7 +70,7 @@ Generate or update each file following the formats in `references/spec-file-form
   - Export/download (if feature exists)
   - Pagination/search (if feature exists)
 
-Full format templates: `references/spec-file-formats.md`
+Full format templates: `../qa-module-analysis/references/spec-file-formats.md`
 
 ---
 
@@ -86,6 +86,12 @@ Full format templates: `references/spec-file-formats.md`
 
 ---
 
+## Quality gates before marking complete
+
+- [ ] Output verification run and the counts reported (see `../qa-module-analysis/references/output-verification.md`) - report the command output, never a compliance claim
+
+---
+
 ## Outputs
 
 - 6 spec files per submodule in `qa/01-specifications/module-{name}/submodule-{name}/`