qa-skills 3.0.0

package/skills/qa-orchestrator/references/scheduler-rules.md

@@ -0,0 +1,84 @@
+# Scheduler Trigger Rules and Automation Patterns
+
+Rules for when to trigger pipelines and what actions to take.
+
+---
+
+## After Merge
+
+**Trigger:** PR merged to main/master (or configured branch)
+
+**Actions:**
+1. Run smoke/regression suite
+2. Generate test report
+3. If failures: invoke qa-bug-ticket-creator for each failure
+
+**Skills invoked:** [test execution] → test-reporter → bug-ticket-creator (conditional)
+
+**Automation pattern:**
+- CI hook (GitHub Actions, etc.) runs tests post-merge
+- Orchestrator consumes results, generates report
+- On failure: create bug tickets with reproduction steps
+
+---
+
+## Before Release
+
+**Trigger:** Release candidate tagged or release branch cut
+
+**Actions:**
+1. Run full regression
+2. Generate completion report
+3. Run risk-analyzer for release scope
+4. Output: release readiness summary
+
+**Skills invoked:** [test execution] → test-reporter → risk-analyzer
+
+**Output:** Completion report + risk summary for sign-off
+
+---
+
+## After Requirement Change
+
+**Trigger:** Requirements/spec document updated
+
+**Actions:**
+1. Impact analysis (affected test cases, specs)
+2. Update RTM (Requirements Traceability Matrix)
+3. Flag tests/specs needing update
+
+**Skills invoked:** spec-auditor (or requirements diff) → coverage-analyzer (RTM) → task-creator (for update tasks)
+
+**Output:** Impact report + tasks for spec/test updates
+
+---
+
+## Scheduler Integration
+
+| Trigger | CI Event | Orchestrator Response |
+| ------- | -------- | --------------------- |
+| After merge | `push` to main | Smoke/regression → report → bug if fail |
+| Before release | `release` tag / workflow | Full regression → completion report + risk |
+| Requirement change | Manual / file watch | Impact analysis → RTM update |
+
+---
+
+## Configuration
+
+Scheduler rules can be configured via:
+- `.cursor/rules/` — project-specific overrides
+- Memory MCP — persisted trigger state
+- Environment — branch names, report paths
+
+---
+
+## Automation Patterns
+
+### Pattern 1: Fail-fast
+On first failure in smoke, stop and create bug. Do not continue full suite.
+
+### Pattern 2: Full report then bugs
+Complete full run, generate report, then create bugs for all failures.
+
+### Pattern 3: Risk-gated
+Before release: if risk-analyzer flags high risk, require additional tests before sign-off.

package/skills/qa-pact-writer/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: qa-pact-writer
+description: Generate consumer-driven contract tests using Pact for JavaScript and Python to verify microservice API compatibility between consumer and provider.
+output_dir: tests/contracts
+dependencies:
+  recommended:
+    - qa-api-contract-curator
+---
+
+# QA Pact Writer
+
+## Purpose
+
+Write consumer-driven contract tests for microservice API compatibility. Transform API contracts (from qa-api-contract-curator) into Pact consumer tests and provider verification tests. Ensure consumer and provider services remain compatible without brittle end-to-end integration tests.
+
+## Key Concepts
+
+| Concept | Description |
+| ------- | ----------- |
+| **Consumer** | Service that makes requests (e.g., frontend, API gateway, another microservice) |
+| **Provider** | Service that serves requests (e.g., REST API, backend service) |
+| **Pact** | Contract/agreement describing expected request/response between consumer and provider |
+| **Pact Broker** | Central repository for publishing, versioning, and sharing pacts |
+| **Consumer-driven** | Consumer defines expectations; provider verifies it meets them |
+
+## Languages & Libraries
+
+| Language | Library | Notes |
+| -------- | ------- | ----- |
+| **JavaScript/TypeScript** | `@pact-foundation/pact` | PactV4 (default), HTTP + async/sync messages |
+| **Python** | `pact-python` | pytest integration, functional state handlers (v2.3+) |
+
+## Workflow
+
+1. **Read API contract** — From qa-api-contract-curator (OpenAPI) or existing endpoint specs
+2. **Write consumer tests** — Define interactions (given state, request, expected response); run tests to generate pact JSON
+3. **Generate pact files** — Pact JSON written to `pacts/` or published to broker
+4. **Write provider verification** — Verify pact against real provider; set up provider states
+5. **Publish to broker** — Publish pacts; run can-i-deploy checks; configure webhooks
+
+## Consumer Side
+
+- **Define interactions** — `given` (provider state), `uponReceiving` (scenario name), request (method, path, headers, body), expected response (status, headers, body)
+- **Run tests** — Consumer tests hit Pact mock server; generate pact JSON on success
+- **Matchers** — `like`, `eachLike`, `term`, `regex` for flexible matching
+
+## Provider Side
+
+- **Verify pact** — Replay interactions from pact against real provider
+- **Provider states** — Set up data/state before each interaction (e.g., "user exists", "order is pending")
+- **State handlers** — Functions or endpoints that prepare provider for each `given` state
+
+## Pact Broker
+
+- **Publish pacts** — Consumer publishes after tests pass
+- **can-i-deploy** — Check if consumer/provider versions are compatible before deployment
+- **Webhooks** — Trigger provider verification when new pacts are published
+
+## Key Patterns
+
+| Pattern | JavaScript | Python |
+| ------- | ---------- | ------ |
+| **Consumer setup** | `new PactV4()` / `new Pact()` | `pact.Consumer(...).has_pact_with(...)` |
+| **Provider verification** | `Verifier.verifyProvider()` | `Verifier(provider=...).verify_pacts()` |
+| **Provider states** | `given()` in interaction | `state_handler` / `set_state` |
+| **Matchers** | `like()`, `eachLike()`, `term()` | `Like`, `EachLike`, `Term` |
+| **Pending pacts** | `pending: true` | `pending: True` |
+| **WIP pacts** | `wip: true` | `wip: True` |
+
+See `references/patterns.md` for consumer tests, provider verification, matchers, provider states.
+
+## Output
+
+- **Consumer tests** — Jest/Vitest (JS) or pytest (Python) files that generate pacts
+- **Provider verification tests** — Scripts or config that verify provider against pacts
+- **Pact JSON contracts** — `{consumer}-{provider}.json` in `pacts/` or broker
+
+## Feeds Into / From
+
+- **qa-api-contract-curator** — Use OpenAPI as input for consumer expectations
+- **qa-supertest-writer** — Consumer tests may use Supertest-like patterns for HTTP
+- **qa-httpx-writer** — Python consumer tests may use httpx for HTTP calls
+
+## Scope
+
+**Can do (autonomous):**
+- Generate consumer tests from API contract (OpenAPI or description)
+- Generate provider verification setup from pact files
+- Define provider states and state handlers
+- Use matchers (like, eachLike, term, regex)
+- Configure Pact Broker publish and verification
+- Add pending/WIP pacts for in-progress work
+- Call qa-api-contract-curator for contract when needed
+
+**Cannot do (requires confirmation):**
+- Change production API implementation
+- Add dependencies not in package.json / requirements.txt
+- Override project test config without approval
+- Deploy or modify Pact Broker infrastructure
+
+**Will not do (out of scope):**
+- Execute tests (user runs `npm test` or `pytest`)
+- Set up or host Pact Broker (use Pactflow, self-hosted broker)
+- Write E2E browser tests (use qa-playwright-ts-writer)
+
+## Quality Checklist
+
+Before delivering Pact tests:
+
+- [ ] Consumer tests define all interactions from API contract
+- [ ] Provider states match consumer `given` clauses
+- [ ] Matchers used for dynamic fields (IDs, timestamps, etc.)
+- [ ] No hardcoded secrets; use env vars for broker URL, tokens
+- [ ] Pact file path or broker config is correct
+- [ ] Provider verification runs against real provider (or documented stub)
+- [ ] Pending/WIP pacts have clear comments on completion criteria
+
+## Troubleshooting
+
+| Symptom | Likely Cause | Fix |
+| ------- | ------------ | --- |
+| Pact mock server port conflict | Port already in use | Change `port` in Pact config; use random port |
+| Provider verification fails | State handler not matching `given` | Ensure state handler name matches consumer `given` exactly |
+| Pact not published to broker | Wrong URL, auth, or version | Verify `PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`; check version in publish |
+| Matcher mismatch on provider | Provider returns different shape | Align consumer matchers with provider response; or fix provider |
+| Consumer test passes, pact empty | Pact not written before teardown | Ensure `executeTest()` / `verify()` completes; check output path |
+| Python state handler not called | Wrong state name or handler signature | Match `given` string; use `state_handler` with correct params (v2.3+) |
+
+## References
+
+- `references/patterns.md` — Consumer tests, provider verification, matchers, provider states
+- `references/config.md` — Pact Broker setup, CI integration, can-i-deploy
+- `references/best-practices.md` — Consumer-driven workflow, versioning, broker management

package/skills/qa-pact-writer/references/best-practices.md

@@ -0,0 +1,100 @@
+# Contract Testing Best Practices
+
+## Consumer-Driven Workflow
+
+1. **Consumer defines expectations** — Consumer team writes tests based on what they need from the API, not what the provider thinks it offers.
+2. **Provider verifies** — Provider team runs verification to ensure they meet consumer expectations.
+3. **Negotiate changes** — When provider cannot meet expectations, teams discuss; consumer may relax expectations or provider may implement.
+
+### Benefits
+
+- Prevents over-specification (provider only implements what consumers need)
+- Catches breaking changes before deployment
+- Reduces need for expensive, brittle E2E tests
+- Enables independent deployment of services
+
+## Versioning
+
+### Consumer Version
+
+- Use deterministic versions: git SHA, semver from package.json
+- Publish on every successful consumer test run
+- Tag with branch for branch-based verification
+
+### Provider Version
+
+- Publish verification results with provider version
+- Link verification to provider deployment pipeline
+- Use same versioning scheme as consumer
+
+### Pact Contract Versioning
+
+- Pact spec version (v3, v4) is separate from application versions
+- Upgrade Pact library when adding new features (e.g., PactV4 for async)
+
+## Broker Management
+
+### Organizing Pacts
+
+- One pact per consumer-provider pair
+- Use consistent naming: `{ConsumerService}-{ProviderService}.json`
+- Tag with environments after successful verification
+
+### Webhooks
+
+- Configure webhook: when consumer publishes pact → trigger provider verification
+- Reduces manual coordination between teams
+- Provider verification can run in provider's CI or a shared contract verification pipeline
+
+### Retention
+
+- Keep pact history for auditing and debugging
+- Consider retention policy for old versions (broker-dependent)
+- Archive or delete pacts for deprecated consumer-provider pairs
+
+## Test Design
+
+### Consumer Tests
+
+- **One interaction per test** — Isolate scenarios; easier to debug
+- **Minimal expectations** — Assert only what the consumer uses
+- **Use matchers** — Avoid exact matches for IDs, timestamps, dynamic data
+- **Descriptive scenario names** — `uponReceiving` should describe the scenario clearly
+
+### Provider States
+
+- **Idempotent** — State setup should be repeatable
+- **Isolated** — No shared state between interactions
+- **Fast** — Prefer in-memory or test DB; avoid slow external calls
+- **Parameterized** — Use params for reusable states (e.g., `userId`)
+
+### Provider Verification
+
+- **Run against real provider** — Use actual app, not mocks (except for provider's own dependencies)
+- **Test DB or fixtures** — Provider states seed data; use separate test DB
+- **Parallel verification** — Verify multiple pacts in parallel when possible
+
+## Pending and WIP Pacts
+
+### Pending Pacts
+
+- New consumer expectations not yet implemented by provider
+- Mark as `pending: true` so provider verification does not fail
+- Remove pending when provider implements and verification passes
+
+### WIP (Work in Progress) Pacts
+
+- In-progress consumer work; pact may change frequently
+- Mark as `wip: true` to exclude from strict verification
+- Use `consumerVersionSelectors` with `wip: true` to include in verification without failing
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Better Approach |
+| ------------ | ------- | --------------- |
+| Copy-pasting provider response | Over-specification; brittle | Use matchers; assert only needed fields |
+| Skipping provider states | Flaky verification | Always define state handlers for `given` |
+| Verifying against mocks | False confidence | Verify against real provider |
+| One giant interaction | Hard to debug | One interaction per scenario |
+| Hardcoded broker URL/token | Security risk | Use env vars |
+| Ignoring pending pacts | Blocked deployments | Use pending; track implementation |

package/skills/qa-pact-writer/references/config.md

@@ -0,0 +1,135 @@
+# Pact Configuration
+
+## Pact Broker Setup
+
+### Environment Variables
+
+| Variable | Description | Required |
+| -------- | ----------- | -------- |
+| `PACT_BROKER_BASE_URL` | Broker URL (e.g., `https://broker.pactflow.io`) | For publish/verify from broker |
+| `PACT_BROKER_TOKEN` | API token for authentication | When broker requires auth |
+| `PACT_BROKER_USERNAME` | Basic auth username | Alternative to token |
+| `PACT_BROKER_PASSWORD` | Basic auth password | Alternative to token |
+
+### Publish Pact (Consumer)
+
+**JavaScript:**
+```json
+{
+  "scripts": {
+    "pact:publish": "pact-broker publish pacts/ --consumer-app-version=$npm_package_version --tag=main"
+  }
+}
+```
+
+**Python:**
+```bash
+pact-broker publish pacts/ --consumer-app-version=1.2.3 --tag=main
+```
+
+### Verify from Broker (Provider)
+
+**JavaScript:**
+```typescript
+await new Verifier({
+  provider: 'UserService',
+  providerBaseUrl: process.env.PROVIDER_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  consumerVersionSelectors: [{ mainBranch: true }],
+}).verifyProvider();
+```
+
+**Python:**
+```python
+verifier.verify_with_broker(
+    broker_url=os.environ['PACT_BROKER_BASE_URL'],
+    broker_token=os.environ['PACT_BROKER_TOKEN'],
+    consumer_version_selectors=[{'mainBranch': True}],
+)
+```
+
+## CI Integration
+
+### Consumer Pipeline
+
+1. Run consumer tests → generates pact JSON
+2. Publish pact to broker with version + branch/tag
+3. Trigger provider verification (via webhook or separate job)
+
+```yaml
+# GitHub Actions example
+- name: Run consumer tests
+  run: npm test -- --grep "Pact"
+
+- name: Publish pact
+  run: npx pact-broker publish pacts/ --consumer-app-version=${{ github.sha }} --branch=${{ github.ref_name }}
+  env:
+    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+    PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+### Provider Pipeline
+
+1. Fetch pacts from broker (or receive webhook)
+2. Start provider (or use running instance)
+3. Run verification against provider
+4. Publish verification results to broker
+
+```yaml
+- name: Verify pacts
+  run: npm run pact:verify
+  env:
+    PROVIDER_URL: http://localhost:3000
+    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+    PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+## can-i-deploy
+
+Check if a consumer or provider version is safe to deploy based on verification status.
+
+```bash
+# Can consumer v1.2.3 be deployed?
+pact-broker can-i-deploy --pacticipant=OrderService --version=1.2.3 --to-environment=production
+
+# Can provider v2.0.0 be deployed?
+pact-broker can-i-deploy --pacticipant=UserService --version=2.0.0 --to-environment=production
+
+# Can both be deployed together?
+pact-broker can-i-deploy --pacticipant=OrderService --version=1.2.3 --pacticipant=UserService --version=2.0.0
+```
+
+### In CI (pre-deploy gate)
+
+```yaml
+- name: Can I deploy?
+  run: |
+    pact-broker can-i-deploy \
+      --pacticipant=OrderService \
+      --version=${{ github.sha }} \
+      --to-environment=staging
+  env:
+    PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+    PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+## Local Development
+
+### Without Broker
+
+- Consumer: write pact to `pacts/` directory
+- Provider: verify from local `pacts/` path
+- Share pact files via git or file copy
+
+### With Broker (Pactflow / self-hosted)
+
+- Use broker for all publish/verify
+- Tag versions with branch names for branch-based verification
+- Use `consumerVersionSelectors` to choose which pacts to verify
+
+## Versioning
+
+- **Consumer version**: Use git SHA, semver, or build number
+- **Provider version**: Same as consumer
+- **Tagging**: Tag with branch (`main`, `develop`) or environment (`production`, `staging`) for can-i-deploy

package/skills/qa-pact-writer/references/patterns.md

@@ -0,0 +1,161 @@
+# Pact Patterns
+
+## Consumer Tests
+
+### JavaScript/TypeScript (PactV4)
+
+```typescript
+import { PactV4 } from '@pact-foundation/pact';
+
+const pact = new PactV4({
+  consumer: 'OrderService',
+  provider: 'UserService',
+  dir: 'pacts',
+});
+
+describe('User API', () => {
+  it('gets user by id', async () => {
+    await pact
+      .addInteraction()
+      .given('user with id 123 exists')
+      .uponReceiving('a request for user 123')
+      .withRequest('GET', '/users/123')
+      .willRespondWith(200, (builder) => {
+        builder.jsonBody({
+          id: builder.like(123),
+          name: builder.like('Alice'),
+          email: builder.term({ matcher: '.*@.*', generate: 'alice@example.com' }),
+        });
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/users/123`);
+        expect(res.status).toBe(200);
+        const body = await res.json();
+        expect(body.name).toBe('Alice');
+      });
+  });
+});
+```
+
+### Python (pact-python)
+
+```python
+import pytest
+from pact import Consumer, Provider
+
+pact = Consumer('OrderService').has_pact_with(Provider('UserService'))
+pact.start_service()
+pact.given('user with id 123 exists').upon_receiving('a request for user 123').with_request(
+    method='GET', path='/users/123'
+).will_respond_with(200, body={'id': Like(123), 'name': Like('Alice'), 'email': Term(r'.*@.*', 'alice@example.com')})
+
+@pytest.fixture
+def user_client():
+    return UserClient(base_url=pact.uri)
+
+def test_get_user(user_client):
+    pact.given('user with id 123 exists').upon_receiving('a request for user 123').with_request(
+        method='GET', path='/users/123'
+    ).will_respond_with(200, body={'id': Like(123), 'name': Like('Alice')})
+    pact.verify()
+    result = user_client.get_user(123)
+    assert result['name'] == 'Alice'
+
+# Teardown: pact.stop_service()
+```
+
+## Provider Verification
+
+### JavaScript
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+
+await new Verifier({
+  provider: 'UserService',
+  providerBaseUrl: process.env.PROVIDER_URL || 'http://localhost:3000',
+  pactUrls: ['pacts/orderservice-userservice.json'],
+  stateHandlers: {
+    'user with id 123 exists': async () => {
+      await seedUser({ id: 123, name: 'Alice', email: 'alice@example.com' });
+    },
+  },
+}).verifyProvider();
+```
+
+### Python
+
+```python
+from pact import Verifier
+
+verifier = Verifier(
+    provider='UserService',
+    provider_base_url='http://localhost:3000',
+)
+verifier.verify_pacts(
+    'pacts/orderservice-userservice.json',
+    state_handler={
+        'user with id 123 exists': lambda: seed_user(id=123, name='Alice', email='alice@example.com'),
+    },
+)
+```
+
+### Functional State Handlers (Python v2.3+)
+
+```python
+def state_handler(state: str, params: dict | None = None) -> dict | None:
+    if state == 'user with id 123 exists':
+        seed_user(id=123, name='Alice', email='alice@example.com')
+        return None
+    if state == 'user has orders':
+        user_id = params.get('userId') if params else None
+        seed_orders(user_id=user_id)
+        return None
+    return None
+
+verifier.verify_pacts('pacts/...', state_handler=state_handler)
+```
+
+## Matchers
+
+| Matcher | Purpose | JS Example | Python Example |
+| ------- | ------- | ---------- | -------------- |
+| **like** | Any value of same type | `builder.like(123)` | `Like(123)` |
+| **eachLike** | Array of objects matching template | `builder.eachLike({ id: 1 })` | `EachLike({'id': 1})` |
+| **term** | Regex match with example | `builder.term({ matcher: '\\d+', generate: '42' })` | `Term(r'\d+', '42')` |
+| **regex** | Alias for term | Same as term | Same as term |
+| **integer** | Integer type | `builder.integer(1)` | `Integer(1)` |
+| **decimal** | Decimal type | `builder.decimal(1.5)` | `Decimal(1.5)` |
+| **boolean** | Boolean type | `builder.boolean(true)` | `Boolean(True)` |
+| **uuid** | UUID format | `builder.uuid()` | `Uuid()` |
+| **datetime** | ISO datetime | `builder.datetime()` | `Datetime()` |
+
+### Matcher Best Practices
+
+- Use `like` for IDs, timestamps, and other dynamic values
+- Use `eachLike` for arrays; specify min count if needed: `eachLike(obj, min=1)`
+- Use `term` when format matters (email, phone, slug)
+- Avoid over-specifying; match only what the consumer needs
+
+## Provider States
+
+### Naming Convention
+
+- Use descriptive, scenario-based names: `user with id X exists`, `order is pending`
+- Match exactly between consumer `given()` and provider state handler key
+- Prefer parameterized states when possible: `user with id {userId} exists`
+
+### State Handler Responsibilities
+
+1. **Setup** — Create data, set DB state, mock external services
+2. **Isolation** — Each interaction runs in isolation; no shared state between interactions
+3. **Teardown** — Clean up after verification (optional; provider may reset per interaction)
+
+### Common Patterns
+
+| State | Setup |
+| ----- | ----- |
+| `user exists` | Insert user into test DB |
+| `user has no orders` | Ensure orders table empty for user |
+| `order is pending` | Insert order with status PENDING |
+| `auth token valid` | Seed valid token or mock auth service |