ma-agents 3.12.0 → 3.12.2

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/webhook-risk-guidance.md

@@ -1,114 +1,114 @@
-# Webhook Testing Risk Guidance
-
-## Principle
-
-Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
-
-## When Webhook Tests Are Required
-
-Webhook tests are **required** (not optional) when:
-
-| Condition                                                          | Rationale                                                              |
-| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
-| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
-| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
-| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
-| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
-| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
-
-## Risk Scoring
-
-```
-Risk = Probability × Impact
-
-Probability factors (P1–P3):
-  P1 (low):    Webhook system is mature, well-tested, no history of failures
-  P2 (medium): Kafka pipeline, multiple consumers, new integrations
-  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
-
-Impact factors (I1–I3):
-  I1 (low):    Non-critical notifications (e.g. audit logs)
-  I2 (medium): Feature-level side effects (e.g. search index updates)
-  I3 (high):   Business-critical events (payments, orders, compliance)
-```
-
-Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
-
-## What a Complete Webhook Test Looks Like
-
-A complete webhook test covers:
-
-1. **Happy path**: Action fires → webhook arrives with correct payload
-2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
-3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
-4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
-5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
-
-**Minimal complete example** (from playwright-utils E2E suite):
-
-```typescript
-// Template factories scoped by ID — parallel safety
-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();
-
-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;
-
-  // Drain: consume the create webhook before testing the delete path
-  await webhookRegistry.waitFor(movieCreated(movieId));
-
-  await deleteMovie(authToken, movieId);
-  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
-
-  expect(webhook.body).toMatchObject({
-    event: 'movie.deleted',
-    data: { id: movieId, name: movie.name },
-  });
-});
-```
-
-## Common Failure Patterns
-
-| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
-| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
-| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
-| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
-| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
-| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
-| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
-| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
-
-## Risk Mitigation Checklist (for TA assessment)
-
-When a system uses webhooks, verify the test suite covers:
-
-- [ ] Happy path for each event type that has an external subscriber
-- [ ] Template factories scoped by entity ID (parallel-safe)
-- [ ] Drain pattern applied to all sequential event assertions
-- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
-- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
-- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
-- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
-
-## Related Fragments
-
-- `webhook-testing-fundamentals.md` — Why webhook tests are hard
-- `webhook-module-setup.md` — Fixture wiring for each provider
-- `webhook-template-matchers.md` — Template and matcher patterns
-- `risk-governance.md` — Risk scoring framework
-- `probability-impact.md` — P×I scale definitions
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+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();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/webhook-template-matchers.md

@@ -1,160 +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
+# 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/agents/bmad-tea/resources/knowledge/webhook-testing-fundamentals.md

@@ -1,42 +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
+# 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