ma-agents 3.6.2 → 3.8.0

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pact-consumer-framework-setup.md

@@ -58,6 +58,8 @@ scripts/
 
 ```typescript
 // vitest.config.pact.ts
+// See pact-consumer-framework-setup.md Example 2 "Key Points" for rationale on
+// fileParallelism + pool:forks + singleFork. Do not remove those three settings.
 import { defineConfig } from 'vitest/config';
 
 export default defineConfig({
@@ -65,13 +67,20 @@ export default defineConfig({
     environment: 'node',
     include: ['tests/contract/**/*.pacttest.ts'],
     testTimeout: 30000,
+    fileParallelism: false,
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
   },
 });
 ```
 
 **Key Points**:
 
-- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- **`fileParallelism: false` is required** — primary defense against non-deterministic pact generation. Without it, parallel workers race on the shared pact JSON file and corrupt interactions. Symptom: local runs pass, CI randomly fails with `Cannot change pact content for already published pact`. See Example 10 for the determinism gate that enforces byte-stability across re-runs.
+- **`pool: 'forks'` + `singleFork: true` is required for multi-file consumer suites** — same config the provider side uses (`pactjs-utils-provider-verifier.md` Example 7). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; with the default threads pool (Vitest v1) and multiple `.pacttest.ts` files on the same consumer+provider pair, we observed reproducible "request was expected but not received" flakes on Linux CI only. `singleFork: true` serializes every pact file into one forked subprocess and eliminated the flake on two repos (`pactjs-utils`, `seon-mcp-server`). Vitest v2+ defaults to `forks`, but set the pool explicitly so the contract does not drift with Vitest version bumps.
+- **Single-file consumer suites** (one `.pacttest.ts` per consumer+provider pair) have not been observed to flake under default threads pool, because FFI state is not shared across files when there is only one file. Adding `pool: 'forks'` is still recommended — it future-proofs you the moment a second file is added — but a suite passing today with only `fileParallelism: false` is not broken.
+- **Interacting settings**: leave `isolate` at its default (`true`). Do NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, or `maxWorkers > 1` in this config — they defeat the serialization this rule relies on. `hookTimeout` may be raised if mock-server startup is slow, but keep `testTimeout` ≥ `hookTimeout`.
+- Do NOT add `setupFiles`, `coverage`, or other settings from the unit test config
 - Keep it minimal — Pact tests run in Node environment with extended timeout
 - 30 second timeout accommodates Pact mock server startup and interaction verification
 - Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
@@ -87,7 +96,8 @@ export default defineConfig({
 ```json
 {
   "scripts": {
-    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "test:pact:consumer": "./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts",
+    "test:pact:consumer:run": "vitest run --config vitest.config.pact.ts",
     "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
     "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
     "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
@@ -99,6 +109,8 @@ Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-fronten
 
 **Key Points**:
 
+- **`test:pact:consumer` IS the determinism gate** — it runs the inner command 3× and fails if pact output is not byte-stable. This is the command CI and developers run before pushing. See Example 10 for the `check-pact-determinism.sh` script itself.
+- **`test:pact:consumer:run` is the fast inner command** for TDD loops (a single pass of the suite, no gate). Developers can iterate with this; CI always goes through the outer gated script.
 - Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
 - Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
 - `PACTICIPANT` is set per-script invocation, not globally
@@ -127,13 +139,19 @@ export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
 export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
 ```
 
-#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker (with defense-in-depth normalization)
 
 ```bash
 #!/bin/bash
-# Publish generated pact files to PactFlow/Pact Broker
+# Publish generated pact files to PactFlow/Pact Broker.
 #
-# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# Before publish, normalize each pact JSON: sort interactions by (description, provider state name,
+# method, path) and sort object keys via `jq -S`. This gives byte-stable output to the broker even
+# if the PactV4 generator produces ordering drift between runs. Paired with scripts/check-pact-determinism.sh
+# as defense-in-depth — the gate catches drift pre-publish; normalization ensures "Cannot change pact
+# content" from PactFlow never fires on ordering-only changes that slip past the gate.
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH, jq
 # -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
 set -euo pipefail
 
@@ -141,6 +159,14 @@ set -euo pipefail
 
 PACT_DIR="./pacts"
 
+# Defense-in-depth: normalize interaction order for byte-stable publishes.
+for f in "$PACT_DIR"/*.json; do
+  tmp="$(mktemp)"
+  jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)' \
+     "$f" > "$tmp"
+  mv "$tmp" "$f"
+done
+
 pact-broker publish "$PACT_DIR" \
     --consumer-app-version="$GITHUB_SHA" \
     --branch="$GITHUB_BRANCH" \
@@ -203,6 +229,7 @@ fi
 - Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
 - `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
 - `record-deployment` has branch guard (only records on main/master)
+- **`publish-pact.sh` normalizes interactions with `jq -S` + `sort_by(...)` before publishing** — defense-in-depth alongside the determinism gate (Example 10). The gate catches drift; normalization ensures byte-stable payload to the broker regardless of generator quirks. Keep both; they protect against different failure modes.
 - Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
 
 ---
@@ -249,11 +276,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      # (1) Generate pact files
-      - name: Run consumer contract tests
+      # (1) Generate pact files — runs the determinism gate (3 runs + byte-stable check via jq)
+      - name: Consumer pact tests (determinism gate)
         run: npm run test:pact:consumer
 
-      # (2) Publish pacts to broker
+      # (2) Publish pacts to broker (publish-pact.sh also normalizes interaction order as defense-in-depth)
       - name: Publish pacts to PactFlow
         run: npm run publish:pact
 
@@ -274,6 +301,8 @@ jobs:
 
 **Key Points**:
 
+- **1:1 local/CI parity is a hard rule**: every CI step is `npm run <same-name-a-dev-uses>`. Never let CI invoke `vitest` or `pact-broker` directly — that divergence is how "works on my machine" slips in. The determinism gate, publish, can-i-deploy, and record-deployment are all the same commands a developer runs locally.
+- **The determinism gate is its own visible step, not a side-effect of publish.** A failing gate must be debuggable from the CI log without re-running. Do not fold it into a `prepublish:pact` hook — folding hides the failure inside a publish log and makes attribution harder.
 - **Workflow-level `env` block** for broker secrets and git vars — not per-step
 - **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
 - **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
@@ -596,12 +625,102 @@ pact-logs/
 
 ---
 
+### Example 10: Determinism Gate Script (Primary Defense)
+
+**Context**: Even with `fileParallelism: false` (Example 2) and one-interaction-per-`it()` (see `pactjs-utils-consumer-helpers.md`), the PactV4 Rust FFI layer can occasionally produce byte-different pact JSON between runs — interaction ordering drift, nested matcher serialization quirks, or `Date` / random-value matchers that weren't locked down. This causes PactFlow to reject re-publishes of the same consumer SHA with `Cannot change pact content for already published pact`. The determinism gate runs the consumer suite N times locally and in CI, hashes the normalized pact files, and fails fast if drift is detected — before any publish is attempted.
+
+**Implementation**:
+
+#### `scripts/check-pact-determinism.sh`
+
+```bash
+#!/bin/bash
+# Run a pact consumer command N times and fail if the generated pact files are not byte-stable.
+# Primary defense against PactV4 non-deterministic output.
+#
+# Usage:  ./scripts/check-pact-determinism.sh "<cmd>" [runs] [pact-dir]
+# Example: ./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts
+#
+# Requires: jq installed on the runner (ubuntu-latest has it; macOS users need `brew install jq`).
+set -euo pipefail
+
+CMD="${1:?usage: ./scripts/check-pact-determinism.sh \"<cmd>\" [runs] [pact-dir]}"
+RUNS="${PACT_DETERMINISM_RUNS:-${2:-3}}"
+PACT_DIR="${3:-./pacts}"
+
+TMP_DIR="$(mktemp -d)"
+trap 'rm -rf "$TMP_DIR"' EXIT
+
+hash_pact_file() {
+  # Sort interactions by (description, first provider state name, method, path), sort keys with -S.
+  # The sorted output is what we hash — so ordering-only drift does NOT count as non-determinism here.
+  # (The gate catches deeper drift; ordering drift is handled by publish-pact.sh normalization.)
+  jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)' "$1" \
+    | shasum -a 256 | awk '{print $1}'
+}
+
+for run in $(seq 1 "$RUNS"); do
+  echo "→ determinism run $run/$RUNS"
+  rm -f "$PACT_DIR"/*.json 2>/dev/null || true
+  eval "$CMD" >"$TMP_DIR/run-$run.log" 2>&1 || {
+    echo "❌ run $run failed — dumping log:"
+    cat "$TMP_DIR/run-$run.log"
+    exit 1
+  }
+  : > "$TMP_DIR/run-$run.hashes"
+  for f in "$PACT_DIR"/*.json; do
+    [ -f "$f" ] || continue
+    printf '%s  %s\n' "$(hash_pact_file "$f")" "$(basename "$f")" >> "$TMP_DIR/run-$run.hashes"
+  done
+  sort -o "$TMP_DIR/run-$run.hashes" "$TMP_DIR/run-$run.hashes"
+done
+
+# Compare every subsequent run against run 1.
+FAIL=0
+for run in $(seq 2 "$RUNS"); do
+  if ! diff -q "$TMP_DIR/run-1.hashes" "$TMP_DIR/run-$run.hashes" >/dev/null; then
+    FAIL=1
+    echo ""
+    echo "❌ Pact output differs between run 1 and run $run:"
+    diff "$TMP_DIR/run-1.hashes" "$TMP_DIR/run-$run.hashes" || true
+  fi
+done
+
+if [ "$FAIL" -ne 0 ]; then
+  echo ""
+  echo "Pact output is non-deterministic across $RUNS runs. Likely causes:"
+  echo "  • multiple .addInteraction() chained in a single it() block (PactV4 FFI drops one non-deterministically)"
+  echo "  • fileParallelism: true in vitest.config.pact.ts (workers race on shared pact JSON)"
+  echo "  • missing pool: 'forks' + singleFork: true (threads pool shares FFI state across files on Linux CI)"
+  echo "  • Date / random matchers that don't lock a stable example value"
+  echo "  • provider state params mutating between runs (e.g. Date.now())"
+  exit 1
+fi
+
+echo "✅ Pact output is byte-stable across $RUNS runs."
+```
+
+**Key Points**:
+
+- **Wire this script into `test:pact:consumer`** (see Example 3). The outer script IS the gate; the inner `test:pact:consumer:run` is the single-pass command for TDD loops.
+- **Default 3 runs** is the sweet spot — 2 runs miss intermittent drops, >3 slows CI without catching more. Override with an env var or the positional arg if you're actively debugging a flake.
+- **Treat gate failures as a P0 bug, not a "retry until green" condition.** Find the source of non-determinism (chained `addInteraction`, unsorted interactions, Date-dependent matchers). Do not raise `RUNS` to 10 to mask the symptom.
+- **Requires `jq`** — installed by default on `ubuntu-latest`. For macOS local dev, document `brew install jq` in the project README.
+- **In CI, make this its own visible step** (see Example 5 step (1) naming). Do not fold into a `prepublish:pact` hook — that hides the failure inside a publish log.
+- **Defense-in-depth with `publish-pact.sh` normalization** (Example 4): the gate catches pre-publish drift; the publish-time `jq` sort ensures any ordering-only drift that slipped past the gate still produces a byte-stable payload to PactFlow.
+
+---
+
 ## Validation Checklist
 
 Before presenting the consumer CDC framework to the user, verify:
 
-- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
-- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] `vitest.config.pact.ts` is minimal **and sets `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`** (`fileParallelism: false` prevents shared pact JSON corruption from parallel workers; forks + `singleFork: true` eliminates the Linux-CI "request was expected but not received" flake observed once a second `.pacttest.ts` is added — see Example 2 Key Points for evidence, mechanism qualifier, and single-file exception)
+- [ ] `vitest.config.pact.ts` does NOT set `sequence.concurrent: true`, `maxConcurrency > 1`, `maxWorkers > 1`, or `isolate: false` — all four defeat the serialization the rule relies on
+- [ ] `package.json` splits `test:pact:consumer` (gated determinism runner) and `test:pact:consumer:run` (inner single-pass command)
+- [ ] `scripts/check-pact-determinism.sh` is present, hashes via `jq -S` + `sort_by`, defaults to 3 runs, and is the body of the `test:pact:consumer` script
+- [ ] `scripts/publish-pact.sh` normalizes interactions with `jq -S '.interactions |= sort_by(.description, (.providerStates[0].name // ""), .request.method, .request.path)'` before the `pact-broker publish` call (defense-in-depth alongside the gate)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `test:pact:consumer:run`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
 - [ ] Scripts source `env-setup.sh` inline in package.json
 - [ ] Shell scripts use `pact-broker` not `npx pact-broker`
 - [ ] Shell scripts use `PACTICIPANT` env var pattern
@@ -611,6 +730,8 @@ Before presenting the consumer CDC framework to the user, verify:
 - [ ] CI workflow named `contract-test-consumer.yml`
 - [ ] CI has workflow-level env block (not per-step)
 - [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step (1) is the determinism gate (calls `npm run test:pact:consumer`) — its own visible step, not folded into publish
+- [ ] CI steps are 1:1 with developer commands — every CI step calls `npm run <same-name>` a dev would run locally (no direct `vitest` or `pact-broker` invocation)
 - [ ] CI step numbering skips (3) — webhook-triggered provider verification
 - [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
 - [ ] CI has NO upload-artifact step
@@ -629,7 +750,8 @@ Before presenting the consumer CDC framework to the user, verify:
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — Library decision tree and installation
-- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
-- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, **one-interaction-per-`it()` rule**
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns; consumer and provider BOTH require `pool: 'forks'` + `singleFork: true` — same FFI-safety rule applies on both sides
 - `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth pattern (dedicated user, classic PAT, PactFlow secret) and staleness monitoring
 - `contract-testing.md` — Foundational CDC patterns and resilience coverage

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pact-mcp.md

@@ -180,6 +180,7 @@ During CI workflow design, reference the can-i-deploy tool:
 
 - `pactjs-utils-overview.md` — runtime utilities that pact tests import
 - `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth pattern and staleness monitoring; `Metrics - All` / `Matrix` MCP tools are useful here for dashboards
 - `contract-testing.md` — foundational contract testing patterns
 
 ## Anti-Patterns

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pactjs-utils-consumer-helpers.md

@@ -185,6 +185,86 @@ await pact
 - Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
 - `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
 
+### Example 6: One `addInteraction()` per `it()` Block (PactV4 Determinism Rule)
+
+**Context**: PactV4's `pact.addInteraction()` feeds the Rust FFI layer that writes interactions to the pact JSON. Chaining multiple `.addInteraction()...executeTest()` blocks inside a single `it()` — or otherwise registering multiple interactions before a single `executeTest` — causes the FFI to **non-deterministically drop whole interactions** (not individual fields) in roughly 1 out of N runs. The pattern passes locally, then fails intermittently in CI or at publish time with `Cannot change pact content for already published pact` once the dropped interaction reappears on a re-run.
+
+**Rule**: Exactly one `pact.addInteraction()` per `it()` block. For N interactions, write N `it()` blocks, or use `it.each(...)`.
+
+```typescript
+// ❌ WRONG — two addInteraction() inside one it() — FFI non-deterministically drops one
+it('handles movie lookup scenarios', async () => {
+  await pact
+    .addInteraction()
+    .given('movie exists')
+    .uponReceiving('a request to get movie by id')
+    .withRequest('GET', '/movies/1')
+    .willRespondWith(200, setJsonBody({ id: integer(1), name: string('The Matrix') }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+
+  // Sometimes this second interaction never makes it to the pact JSON:
+  await pact
+    .addInteraction()
+    .given('no movies exist')
+    .uponReceiving('a request for an empty list')
+    .withRequest('GET', '/movies')
+    .willRespondWith(200, setJsonBody([]))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+// ✅ RIGHT — one addInteraction() per it()
+it('gets a movie by id', async () => {
+  await pact
+    .addInteraction()
+    .given('movie exists')
+    .uponReceiving('a request to get movie by id')
+    .withRequest('GET', '/movies/1')
+    .willRespondWith(200, setJsonBody({ id: integer(1), name: string('The Matrix') }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+it('returns empty list when no movies exist', async () => {
+  await pact
+    .addInteraction()
+    .given('no movies exist')
+    .uponReceiving('a request for an empty list')
+    .withRequest('GET', '/movies')
+    .willRespondWith(200, setJsonBody([]))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+
+// ✅ RIGHT — parameterized via it.each for data-driven coverage
+it.each([
+  { id: 1, name: 'The Matrix' },
+  { id: 2, name: 'Inception' },
+])('gets movie $id', async ({ id, name }) => {
+  await pact
+    .addInteraction()
+    .given('movie exists', { id, name })
+    .uponReceiving(`a request to get movie ${id}`)
+    .withRequest('GET', `/movies/${id}`)
+    .willRespondWith(200, setJsonBody({ id: integer(id), name: string(name) }))
+    .executeTest(async (mockServer) => {
+      /* ... */
+    });
+});
+```
+
+**Key Points**:
+
+- **This rule stacks with two other MANDATORY vitest settings**: `fileParallelism: false` AND `pool: 'forks'` with `poolOptions.forks.singleFork: true`. All three are required and address different failure modes — `fileParallelism: false` prevents parallel workers from racing on the shared pact JSON; `pool: 'forks'` + `singleFork: true` prevents the Pact Rust FFI from leaking state across files (manifests as "request was expected but not received" flakes on Linux CI only); one-interaction-per-`it()` prevents the FFI from dropping interactions within a single test body.
+- Symptom of violating this rule: the pact file is byte-different between otherwise-identical runs; `scripts/check-pact-determinism.sh` flags drift; PactFlow rejects a republish with `Cannot change pact content`.
+- The rule applies to both HTTP consumer pacts (`PactV4`) and message consumer pacts (`MessageConsumerPact`).
+- See `pact-consumer-framework-setup.md` Example 10 for the determinism gate that automatically catches violations of this rule.
+
 ## Key Points
 
 - **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
@@ -198,11 +278,13 @@ await pact
 - **Body shorthand**: `setJsonBody` keeps body-only responses concise and readable
 - **Matchers check type, not value**: `string('My movie')` means "any string", `integer(1)` means "any integer". The example values are arbitrary — the provider can return different values and verification still passes as long as the type matches. Use matchers only in `.willRespondWith()` (responses), never in `.withRequest()` (requests) — Postel's Law applies.
 - **Reuse test values across files**: Interactions are uniquely identified by `uponReceiving` + `.given()`, not by placeholder values. Two test files can both use `testId: 100` without conflicting. On the provider side, shared values simplify state handlers — idempotent handlers (check if exists, create if not) only need to ensure one record exists. Use different values only when testing different states of the same entity type (e.g., `movieExists(100)` for happy paths vs. `movieNotFound(999)` for error paths).
+- **One `addInteraction()` per `it()` block (MANDATORY for PactV4)**: Multiple interactions inside one `it()` cause the Rust FFI to non-deterministically drop interactions. Use one `it()` per interaction or `it.each(...)` for parameterized cases. See Example 6 and the determinism gate in `pact-consumer-framework-setup.md` Example 10.
 
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
-- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation; same `pool: 'forks'` + `singleFork: true` rule as consumer
+- `pact-consumer-framework-setup.md` — Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true` config, determinism gate (Example 10), and CI wiring
 - `contract-testing.md` — foundational patterns with raw Pact.js
 
 ## Anti-Patterns
@@ -267,4 +349,32 @@ provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id:
 .willRespondWith(200, setJsonBody({ status: 200 }));
 ```
 
+### Wrong: Multiple `addInteraction()` in a single `it()`
+
+```typescript
+// ❌ PactV4 FFI non-deterministically drops one of these interactions ~1/N runs
+it('handles both success and empty list', async () => {
+  await pact.addInteraction().uponReceiving('get movie').withRequest(/* ... */).executeTest(/* ... */);
+  await pact.addInteraction().uponReceiving('empty list').withRequest(/* ... */).executeTest(/* ... */);
+});
+```
+
+### Right: One `addInteraction()` per `it()` (or use `it.each`)
+
+```typescript
+// ✅ Deterministic pact JSON — FFI receives one interaction per test
+it('gets a movie', async () => {
+  await pact
+    .addInteraction() /* ... */
+    .executeTest(/* ... */);
+});
+it('returns empty list', async () => {
+  await pact
+    .addInteraction() /* ... */
+    .executeTest(/* ... */);
+});
+```
+
+See Example 6 above for the full rationale and the determinism gate that enforces this rule.
+
 _Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pactjs-utils-overview.md

@@ -28,6 +28,7 @@ Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminat
 - **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
 - **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
 - **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+- **`zodToPactMatchers`**: Converts a Zod schema (+ optional example values or `.openapi({ example })` metadata) into Pact V3 matchers — single source of truth for response shape, no hand-written matcher helpers
 
 ## Installation
 
@@ -42,18 +43,19 @@ npm install -D @pact-foundation/pact
 
 ## Available Utilities
 
-| Category          | Function                          | Description                                          | Use Case                                                         |
-| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
-| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
-| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
-| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
-| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
-| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
-| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
-| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
-| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
-| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
-| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+| Category          | Function                          | Description                                          | Use Case                                                                                                  |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`                                                   |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                                                          |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders                                           |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                                                               |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))`                                          |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                                                         |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                                                            |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                                                            |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                                                                  |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                                                                       |
+| Schema → Matchers | `zodToPactMatchers`               | Derives Pact V3 matchers from a Zod schema           | Consumer tests: response body matchers from a consumer-curated Zod schema instead of hand-written helpers |
 
 ## Decision Tree: Which Flow?
 
@@ -153,6 +155,7 @@ await new Verifier(opts).verifyProvider();
 - `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
 - `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
 - `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `pactjs-utils-zod-to-pact.md` — detailed zodToPactMatchers usage, consumer-curated schema pattern, and anti-patterns
 - `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
 - `test-levels-framework.md` — where contract tests fit in the testing pyramid
 

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/knowledge/pactjs-utils-provider-verifier.md

@@ -220,6 +220,54 @@ const tags = getProviderVersionTags();
 //   tags = ['local']
 ```
 
+### Example 7: Provider Vitest Configuration (Required for Multi-File Verification)
+
+**Context**: The Pact Rust FFI that powers the JS `Verifier` holds process-wide state (native handles for messages, matchers, mocks). Vitest's default parallel file workers each spin up their own FFI instance and quickly corrupt that state — causing `MessagePact`/`Verifier` errors like `"Unable to get the MessageHandle"`, or non-deterministic verification passes/fails — as soon as you have more than one provider `.spec.ts` file.
+
+**Rule**: Provider verification suites **must** run in a single fork. Use Vitest's `forks` pool with `singleFork: true` in `vitest.config.contract.ts` (or equivalent).
+
+```typescript
+// vitest.config.contract.ts — provider verification config
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.spec.ts'],
+    testTimeout: 60000,
+    // MANDATORY for multi-file provider verification.
+    // The Pact Rust FFI backing the Verifier holds process-wide state; parallel workers corrupt it
+    // and produce flaky verification results / "Unable to get the MessageHandle" errors.
+    // This is especially important for message providers (Kafka/async) where verifier construction
+    // allocates native handles per file — singleFork keeps them in one process so state is coherent.
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+});
+```
+
+**Key Points**:
+
+- **Required for message providers** (`buildMessageVerifierOptions`) — the message-handle FFI state is almost guaranteed to corrupt under parallel workers.
+- **Required for HTTP providers with multiple contract test files** — even if each file works in isolation, running them together in parallel produces intermittent failures.
+- `pool: 'forks'` (rather than `threads`) + `singleFork: true` is the exact combo that keeps all verifier runs in a single child process with a single FFI instance.
+- Treat `pool: 'forks'` + `singleFork: true` as the required baseline for all provider suites, including single-file HTTP-only ones. A suite that works today with one file will flake the moment a second file is added, and removing the setting later introduces a regression window.
+- **The same `pool: 'forks'` + `singleFork: true` rule applies on the consumer side.** Consumer `vitest.config.pact.ts` sets it alongside `fileParallelism: false` — see `pact-consumer-framework-setup.md` Example 2. The rule is needed on either side wherever more than one pact test file exists per consumer+provider pair.
+- Use a dedicated `vitest.config.contract.ts` so unit tests still get full parallelism — only contract tests pay the serialization cost.
+- Related `package.json` entry:
+
+  ```json
+  {
+    "scripts": {
+      "test:pact:provider": "vitest run --config vitest.config.contract.ts"
+    }
+  }
+  ```
+
 ## Environment Variables Reference
 
 | Variable               | Required        | Description                                                                                                                           | Default     |
@@ -241,12 +289,15 @@ const tags = getProviderVersionTags();
 - **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
 - **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
 - **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+- **Provider Vitest config is MANDATORY for multi-file suites**: Set `pool: 'forks'` + `poolOptions.forks.singleFork: true` in `vitest.config.contract.ts`. Without this the Rust FFI corrupts under parallel workers (see Example 7).
 
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
-- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation, **one-interaction-per-`it()` rule**
 - `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `pact-consumer-framework-setup.md` — consumer-side framework setup, Vitest `fileParallelism: false`, determinism gate
+- `pact-broker-webhooks.md` — PactFlow → GitHub webhook auth/staleness for webhook-triggered provider verification (`contract_requiring_verification_published`)
 - `contract-testing.md` — foundational patterns with raw Pact.js
 
 ## Anti-Patterns
@@ -312,4 +363,35 @@ const opts = buildVerifierOptions({
 // Selectors chosen automatically based on environment
 ```
 
+### Wrong: Parallel Vitest workers for provider verification
+
+```typescript
+// ❌ vitest.config.contract.ts — uses default parallel workers
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.spec.ts'],
+    // NO pool/singleFork config — defaults to parallel file workers
+  },
+});
+// Symptoms: "Unable to get the MessageHandle", non-deterministic verification pass/fail,
+// green locally on single-file run but red in CI with multiple files
+```
+
+### Right: Single fork for provider verification
+
+```typescript
+// ✅ vitest.config.contract.ts — serializes provider verification files
+import { defineConfig } from 'vitest/config';
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.spec.ts'],
+    pool: 'forks',
+    poolOptions: { forks: { singleFork: true } },
+  },
+});
+```
+
 _Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_