ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/resources/knowledge/webhook-template-matchers.md

@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+const batchTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.created.batch')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${id1} or ${id2}`, (p) => p.data.id === id1 || p.data.id === id2)
+  .withTimeout(15_000)
+  .withInterval(500)
+  .build();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/resources/knowledge/webhook-testing-fundamentals.md

@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/resources/knowledge/webhook-timeout-error.md

@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/resources/knowledge/webhook-waiting-querying.md

@@ -0,0 +1,167 @@
+# Webhook Waiting and Querying Patterns
+
+## Principle
+
+`waitFor` and `waitForCount` poll until matching webhooks arrive; `getReceived` queries without waiting. Always drain preceding events before asserting on subsequent ones. Scope templates by entity ID to prevent parallel worker cross-contamination.
+
+## Pattern Examples
+
+### Example 1: waitFor — single webhook
+
+Poll until the first webhook matching the template arrives. Returns the typed `ReceivedWebhook<T>`.
+
+```typescript
+const webhook = await webhookRegistry.waitFor(movieCreated(movieId));
+
+expect(webhook.body).toMatchObject({
+  event: 'movie.created',
+  timestamp: expect.any(String),
+  data: {
+    id: movieId,
+    name: movie.name,
+    year: movie.year,
+    rating: movie.rating,
+  },
+});
+```
+
+### Example 2: The drain pattern — sequential events
+
+When testing a downstream event (e.g. deletion), always `waitFor` the preceding event first. Without the drain, the create webhook may remain in the journal and interfere with cleanup or subsequent polling.
+
+```typescript
+test('movie deletion triggers a webhook with correct payload', async ({ authToken, addMovie, deleteMovie, webhookRegistry }) => {
+  const movie = generateMovieWithoutId();
+  const { body: createResponse } = await addMovie(authToken, movie);
+  const movieId = createResponse.data.id;
+
+  await log.step('Drain the create webhook before testing the delete path');
+  await webhookRegistry.waitFor(movieCreated(movieId)); // drain — consume the create event
+
+  await deleteMovie(authToken, movieId);
+
+  await log.step('Wait for the delete webhook');
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+**Why drain?** If you skip the drain and go directly to `waitFor(movieDeleted)`, the create webhook is already in the journal. The delete webhook may arrive and be cleaned up by another test before your poll reaches it. Draining makes the event order explicit and removes the ambiguity.
+
+### Example 3: waitForCount — collect N webhooks concurrently
+
+Collect exactly N matching webhooks. Use `matchPredicate` with all IDs to prevent cross-worker contamination when running `fullyParallel: true`:
+
+```typescript
+await log.step('Create two movies concurrently');
+const [{ body: res1 }, { body: res2 }] = await Promise.all([
+  addMovie(authToken, generateMovieWithoutId()),
+  addMovie(authToken, generateMovieWithoutId()),
+]);
+
+const [id1, id2] = [res1.data.id, res2.data.id];
+
+const batchTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.created.batch')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${id1} or ${id2}`, (p) => p.data.id === id1 || p.data.id === id2)
+  .withTimeout(15_000)
+  .withInterval(500)
+  .build();
+
+const webhooks = await webhookRegistry.waitForCount(batchTemplate, 2);
+
+expect(webhooks).toHaveLength(2);
+const receivedIds = webhooks.map((w) => w.body.data.id);
+expect(receivedIds).toContain(id1);
+expect(receivedIds).toContain(id2);
+expect(new Set(receivedIds).size).toBe(2); // guard against the same ID delivered twice
+```
+
+### Example 4: getReceived — query without waiting
+
+Query the journal without polling. Useful for asserting presence of webhooks after a `waitFor`, or for method/URL filtering.
+
+```typescript
+await webhookRegistry.waitFor(movieCreated(movieId)); // wait first
+
+const all = await webhookRegistry.getReceived();
+expect(all.length).toBeGreaterThanOrEqual(1);
+
+// Method filter — all sample-app webhooks are delivered via POST
+const postOnly = await webhookRegistry.getReceived({ method: 'POST' });
+expect(postOnly.every((w) => w.method === 'POST')).toBe(true);
+
+// URL pattern filter — match the webhooks endpoint path
+const byUrl = await webhookRegistry.getReceived({ urlPattern: '/webhooks' });
+expect(byUrl.every((w) => w.url.includes('/webhooks'))).toBe(true);
+```
+
+`getReceived` accepts `WebhookQueryFilter`:
+
+```typescript
+type WebhookQueryFilter = {
+  urlPattern?: string; // glob or regex string
+  method?: string; // HTTP method filter
+  since?: Date; // only return webhooks after this timestamp
+};
+```
+
+Note: `getReceived` is a direct passthrough to the provider — it does **not** automatically apply the `startedAt` filter. Only `waitFor` and `waitForCount` apply the since-filter internally during polling. If you need to scope a manual `getReceived` call to this test's time window, record your own timestamp before the action under test and pass `{ since: myTimestamp }` explicitly.
+
+## Parallel Worker Safety
+
+Always scope template factories to the entity's ID:
+
+```typescript
+// ✅ Scoped — only matches webhooks for this specific movie
+const movieCreated = (movieId: number) =>
+  webhookTemplate('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId) // scoped by ID
+    .build();
+
+// ❌ Unscoped — will match any movie.created from any parallel worker
+const movieCreatedUnscoped = webhookTemplate('movie.created').matchField('event', 'movie.created').build();
+```
+
+## Method Summary
+
+| Method                      | Returns                         | Description                                                                                       |
+| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `waitFor(template)`         | `Promise<ReceivedWebhook<T>>`   | Poll until first match; throws `WebhookTimeoutError` on timeout                                   |
+| `waitForCount(template, n)` | `Promise<ReceivedWebhook<T>[]>` | Poll until N matches; throws `WebhookTimeoutError` on timeout                                     |
+| `getReceived(filter?)`      | `Promise<ReceivedWebhook[]>`    | Direct passthrough to provider — no automatic since-filter; pass `{ since }` explicitly if needed |
+| `resetJournal()`            | `Promise<void>`                 | Wipe the entire journal and clear matchedIds                                                      |
+| `cleanup()`                 | `Promise<void>`                 | Delete matched webhooks (`matched-only`) or reset journal (`full-reset`)                          |
+
+## Anti-Patterns
+
+**DON'T skip the drain for sequential events:**
+
+```typescript
+// Bad: direct jump to delete webhook — create webhook pollutes the journal
+await addMovie(authToken, movie);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+**DO drain preceding events:**
+
+```typescript
+// Good: drain create first, then wait for delete
+await webhookRegistry.waitFor(movieCreated(movieId)); // drain
+await deleteMovie(authToken, movieId);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — How to build templates
+- `webhook-timeout-error.md` — What to do when waitFor times out
+- `recurse.md` — The polling primitive used internally by the registry

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/resources/tea-index.csv

@@ -7,7 +7,7 @@ playwright-config,Playwright Config Guardrails,"Environment switching, timeout s
 ci-burn-in,CI and Burn-In Strategy,"Staged jobs, shard orchestration, burn-in loops, artifact policy","ci,automation,flakiness",extended,knowledge/ci-burn-in.md
 selective-testing,Selective Test Execution,"Tag/grep usage, spec filters, diff-based runs, promotion rules","risk-based,selection,strategy",extended,knowledge/selective-testing.md
 feature-flags,Feature Flag Governance,"Enum management, targeting helpers, cleanup, release checklists","feature-flags,governance,launchdarkly",specialized,knowledge/feature-flags.md
-contract-testing,Contract Testing Essentials,"Pact publishing, provider verification, resilience coverage","contract-testing,pact,api,backend,microservices,service-contract",specialized,knowledge/contract-testing.md
+contract-testing,Contract Testing Essentials,"Pact publishing, provider verification, resilience coverage, PactV4 four-rule determinism & FFI safety block (fileParallelism + pool:forks + singleFork + determinism gate)","contract-testing,pact,api,backend,microservices,service-contract,vitest,ffi,determinism,pactv4",specialized,knowledge/contract-testing.md
 email-auth,Email Authentication Testing,"Magic link extraction, state preservation, caching, negative flows","email-authentication,security,workflow",specialized,knowledge/email-auth.md
 error-handling,Error Handling Checks,"Scoped exception handling, retry validation, telemetry logging","resilience,error-handling,stability,api,backend",extended,knowledge/error-handling.md
 visual-debugging,Visual Debugging Toolkit,"Trace viewer usage, artifact expectations, accessibility integration","debugging,dx,tooling,ui",specialized,knowledge/visual-debugging.md
@@ -33,11 +33,19 @@ network-error-monitor,Network Error Monitor,"HTTP 4xx/5xx detection for UI tests
 fixtures-composition,Fixtures Composition,"mergeTests composition patterns for combining utilities","fixtures,playwright-utils",extended,knowledge/fixtures-composition.md
 api-testing-patterns,API Testing Patterns,"Pure API test patterns without browser: service testing, microservices, GraphQL","api,backend,service-testing,api-testing,microservices,graphql,no-browser",specialized,knowledge/api-testing-patterns.md
 pactjs-utils-overview,Pact.js Utils Overview,"Installation, contract testing flows, utility table (createProviderState, toJsonMap, setJsonContent, setJsonBody)","pactjs-utils,contract-testing,pact,api,backend,microservices",specialized,knowledge/pactjs-utils-overview.md
-pactjs-utils-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
-pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody; PactV4 one-interaction-per-it() determinism rule","pactjs-utils,consumer,contract-testing,pact,api,determinism,pactv4",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions; vitest pool:forks + singleFork for FFI safety (same rule applies to consumer and provider)","pactjs-utils,provider,consumer,contract-testing,pact,api,backend,ci,vitest,ffi",specialized,knowledge/pactjs-utils-provider-verifier.md
 pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
 pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
-pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config with fileParallelism:false + pool:forks + singleFork:true (FFI safety), determinism gate (check-pact-determinism.sh), jq-normalized publishing, 1:1 local/CI parity, PactV4 patterns","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts,determinism,jq,pactv4,ffi",specialized,knowledge/pact-consumer-framework-setup.md
+pact-broker-webhooks,Pact Broker Webhooks,"PactFlow → GitHub repository_dispatch auth via dedicated machine user + classic PAT (repo scope, no expiration) + PactFlow secret; staleness monitoring and PAT rotation runbook","pact,pactflow,broker,webhooks,github,auth,pat,ci,operations,security",specialized,knowledge/pact-broker-webhooks.md
 adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
 playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
 pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/steps-c/step-01-preflight.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-01-preflight'
 description: 'Verify prerequisites and detect CI platform'
-nextStepFile: './step-02-generate-pipeline.md'
+nextStepFile: '{skill-root}/steps-c/step-02-generate-pipeline.md'
 outputFile: '{test_artifacts}/ci-pipeline-progress.md'
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/steps-c/step-02-generate-pipeline.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-02-generate-pipeline'
 description: 'Generate CI pipeline configuration with adaptive orchestration (agent-team, subagent, or sequential)'
-nextStepFile: './step-03-configure-quality-gates.md'
+nextStepFile: '{skill-root}/steps-c/step-03-configure-quality-gates.md'
 knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/ci-pipeline-progress.md'
 ---
@@ -191,8 +191,11 @@ Write the selected pipeline configuration to the resolved output path from step
 
 **If `tea_use_pactjs_utils` is enabled**, use `{knowledgeIndex}` to load:
 
-- `pactjs-utils-provider-verifier.md` — `buildVerifierOptions`, broker config, and breaking change patterns for CI provider verification
+- `pact-consumer-framework-setup.md` — determinism gate, `jq -S` publish normalization, 1:1 local/CI parity, full consumer CI workflow template
+- `pactjs-utils-consumer-helpers.md` — one-interaction-per-`it()` determinism rule
+- `pactjs-utils-provider-verifier.md` — `buildVerifierOptions`, broker config, breaking change patterns, **vitest `pool: 'forks'` + `singleFork: true`** (same rule applies to consumer AND provider configs)
 - `pactjs-utils-request-filter.md` — `createRequestFilter` auth injection patterns for CI pipeline auth setup
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth (dedicated machine user, classic PAT with `repo` scope, PactFlow-stored secret), rotation runbook, and staleness monitoring options (the webhook is what makes `can-i-deploy` succeed end-to-end)
 
 When `tea_use_pactjs_utils` is enabled, add a `contract-test` stage after `test`:
 
@@ -208,23 +211,26 @@ env:
 
 > **Note:** `GITHUB_SHA` is auto-set by GitHub Actions, but `GITHUB_BRANCH` is **not** — it must be derived from `github.head_ref` (for PRs) or `github.ref_name` (for pushes). The pactjs-utils library reads both from `process.env`.
 
-1. **Consumer test + publish**: Run consumer contract tests, then publish pacts to broker
-   - `npm run test:pact:consumer`
-   - `npm run publish:pact`
-   - Only publish on PR and main branch pushes
+1. **Consumer test (determinism gate) + publish**: Run consumer contract tests as a determinism gate, then publish pacts to broker — each step calls the same `npm run` script a developer runs locally (1:1 parity)
+   - `npm run test:pact:consumer` — **this is the determinism gate**: runs `scripts/check-pact-determinism.sh` which invokes the inner `test:pact:consumer:run` N times (default 3) and fails if generated pact JSON is not byte-stable across runs. Never fold this into the publish step — keep it as its own visible CI step so failures are attributable to generation vs publish.
+   - `npm run publish:pact` — publishes to the broker; internally normalizes interactions via `jq -S '.interactions |= sort_by(...)'` as defense-in-depth against any ordering drift that slips past the gate.
+   - Ensure `jq` is available on the runner. It is preinstalled on GitHub `ubuntu-latest`; for other runner images or self-hosted runners, add an explicit install step (e.g., `apt-get install -y jq` or `brew install jq`) before any contract-test or publish command.
+   - Only publish on PR and main branch pushes.
 
 2. **Provider verification**: Run provider verification against published pacts
    - `npm run test:pact:provider:remote:contract`
    - `buildVerifierOptions` auto-reads `PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`, `GITHUB_SHA`, `GITHUB_BRANCH`
+   - Provider Vitest config (`vitest.config.contract.ts`) **must** use `pool: 'forks'` + `poolOptions.forks.singleFork: true` (see `pactjs-utils-provider-verifier.md` Example 7) — required for message providers and any multi-file provider contract suite to keep Pact Rust FFI state coherent. The SAME config is required on the consumer side (`vitest.config.pact.ts`) alongside `fileParallelism: false` — see `pact-consumer-framework-setup.md` Example 2.
    - Verification results published to broker when `CI=true`
 
 3. **Can-I-Deploy gate**: Block deployment if contracts are incompatible
    - `npm run can:i:deploy:provider`
    - Ensure the script adds `--retry-while-unknown 6 --retry-interval 10` for async verification
 
-4. **Webhook job**: Add `repository_dispatch` trigger for `pact_changed` event
+4. **Webhook job**: Add `repository_dispatch` trigger for `contract_requiring_verification_published` event
    - Provider verification runs when consumers publish new pacts
    - Ensures compatibility is checked on both consumer and provider changes
+   - Webhook authentication uses a dedicated GitHub machine user + classic PAT (`repo` scope, no expiration) stored as a PactFlow secret. See `pact-broker-webhooks.md` for the full pattern, rotation runbook, and staleness monitoring. A silently-expired PAT is the most common non-code cause of `can-i-deploy` timeouts with `There is no verified pact between ...`.
 
 5. **Breaking change handling**: When `PACT_BREAKING_CHANGE=true` env var is set:
    - Provider test passes `includeMainAndDeployed: false` to `buildVerifierOptions` — verifies only matching branch
@@ -233,6 +239,8 @@ env:
 6. **Record deployment**: After successful deployment, record version in broker
    - `npm run record:provider:deployment --env=production`
 
+7. **Staleness monitoring (recommended)**: Scheduled CI job (e.g., daily) that asserts recent verification results exist for each critical consumer/provider pair — surfaces silent webhook failures before they block a release. See `pact-broker-webhooks.md` Example 4.
+
 Required CI secrets: `PACT_BROKER_BASE_URL`, `PACT_BROKER_TOKEN`
 
 **If `tea_pact_mcp` is `"mcp"`:** Reference the SmartBear MCP `Can I Deploy` and `Matrix` tools for pipeline guidance in `pact-mcp.md`.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-ci/steps-c/step-03-configure-quality-gates.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-03-configure-quality-gates'
 description: 'Configure burn-in, quality gates, and notifications'
-nextStepFile: './step-04-validate-and-summary.md'
+nextStepFile: '{skill-root}/steps-c/step-04-validate-and-summary.md'
 knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/ci-pipeline-progress.md'
 ---
@@ -85,13 +85,18 @@ Define:
 
 Use `{knowledgeIndex}` to load:
 
-- `pactjs-utils-provider-verifier.md` — `buildVerifierOptions`, broker config, and breaking change patterns for provider verification gates
+- `pact-consumer-framework-setup.md` — determinism gate (`check-pact-determinism.sh`), `jq -S` publish normalization, 1:1 local/CI parity
+- `pactjs-utils-consumer-helpers.md` — one-interaction-per-`it()` determinism rule
+- `pactjs-utils-provider-verifier.md` — `buildVerifierOptions`, broker config, breaking change patterns, vitest `pool: 'forks'` + `singleFork` (same rule applies to consumer AND provider)
 - `pactjs-utils-request-filter.md` — `createRequestFilter` auth injection patterns for CI pipeline auth setup
+- `pact-broker-webhooks.md` — webhook auth pattern, PAT rotation runbook, staleness monitoring (webhook failures silently break `can-i-deploy`)
 
+- **Determinism gate must pass** (consumer side): `npm run test:pact:consumer` runs the suite N times and fails on byte-different pact JSON before any publish is attempted. This is a non-negotiable pre-publish gate.
 - **can-i-deploy must pass** before any deployment to staging or production
 - Block the deployment pipeline if contract verification fails
 - Treat consumer pact publishing failures as CI failures (contracts must stay up-to-date)
 - Provider verification must pass for all consumer pacts before merge
+- **Staleness alert**: scheduled job asserts recent verifications exist — a missing signal indicates a silently-broken webhook (usually an expired GitHub PAT on the PactFlow secret; see `pact-broker-webhooks.md` rotation runbook).
 
 ---