bmad-method-test-architecture-enterprise 1.23.4 → 1.24.0

package/.claude-plugin/marketplace.json

@@ -31,7 +31,7 @@
       "name": "bmad-method-test-architecture-enterprise",
       "source": "./",
       "description": "Master Test Architect module for quality strategy, test automation, CI/CD quality gates, and structured testing education. Part of the BMad Method ecosystem.",
-      "version": "1.23.4",
+      "version": "1.24.0",
       "author": {
         "name": "Murat K Ozcan (TEA Creator) & Brian (BMad) Madison"
       },

package/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.24.0] - 2026-09-01
+
+### Changed
+
+- Pact guidance now covers the short-lived branch coordination shipped in
+  `@seontechnologies/pactjs-utils` 1.2.0: scoped `consumerBranch` selectors for
+  HTTP and message provider verification, PR-only consumer/provider branch
+  detection, exact PactFlow provider-revision checkout, and an additive
+  `can-i-deploy` branch check that preserves the environment-wide safety gate.
+  It also adopts `isBreakingChangeTolerantBranch` with the explicit-consumer
+  no-pacts guard that prevents typo-driven false greens. The Pact mandate,
+  framework scaffolding, knowledge selection metadata, and public integration
+  documentation use the same rules.
+
+### Fixed
+
+- Documentation builds clear Astro's content cache before reading the symlinked
+  `docs/` tree, preventing duplicate content IDs on repeated builds.
+
 ## [1.23.4] - 2026-08-31
 
 ### Fixed

package/docs/how-to/customization/integrate-pactjs-utils.md

@@ -134,6 +134,53 @@ await new Verifier(
 
 State handler names and their `params` must match the consumer's `createProviderState` exactly. That pairing is the contract's own contract.
 
+## Coordinate Different PR Branch Names
+
+`matchingBranch: true` covers teams that use the same branch name in consumer
+and provider repositories. Pact.js Utils 1.2.0 also covers short-lived branches
+with different names.
+
+On the provider side, `buildVerifierOptions` and
+`buildMessageVerifierOptions` accept `consumerBranch`, defaulting to
+`PACT_CONSUMER_BRANCH`:
+
+```typescript
+buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  consumer: 'SampleAppConsumer',
+  consumerBranch: process.env.PACT_CONSUMER_BRANCH,
+});
+```
+
+The explicit selector is scoped to `consumer`; the builders throw when a
+consumer branch is supplied without one. It stays alongside the matching,
+main, and deployed selectors.
+
+On the consumer side, copy the package's `detect-provider-branch` composite
+action and add `Pact provider branch: <name>` to the PR template. During the PR,
+`can-i-deploy.sh`:
+
+1. checks the target environment while ignoring only that named provider;
+2. checks the same consumer version against the provider branch tip.
+
+Both calls are required. A branch check proves less than an environment check,
+so the override is read on pull requests only and disappears on push to main.
+
+The provider has a mirror `detect-consumer-branch` action for manual
+coordination. Keep that PR flow separate from PactFlow's
+`contract_requiring_verification_published` webhook. The webhook identifies an
+exact provider version that needs a result. Check out its
+`providerVersionNumber`, verify that commit belongs to
+`providerVersionBranch`, and publish against those values.
+
+Provider suites with an explicit breaking-change tolerance policy should use
+`isBreakingChangeTolerantBranch`. It recognizes only `main`, `master`, and
+`release/**`. Check and reject a missing hand-entered `PACT_CONSUMER_BRANCH`
+before applying that tolerance, so a typo cannot turn an unexecuted
+cross-branch verification green.
+
 ## Which Workflows Change
 
 | Workflow      | What the flag changes                                                                                                                                                                              |

package/docs/reference/knowledge-base.md

@@ -139,16 +139,16 @@ Contract testing fundamentals plus Pact.js Utils, Pact MCP, and broker operation
 
 | Fragment                                                                                                                                                                                        | Tier        | Description                                                                                                                                                               | Key Topics                                      |
 | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
-| [contract-testing](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/contract-testing.md)                             | specialized | Raw Pact patterns, publishing, verification, resilience, PactV4 four-rule determinism and FFI safety block                                                                | Contract testing, Pact fundamentals             |
-| [pactjs-utils-overview](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-overview.md)                   | specialized | Installation, flow decision tree, utility map                                                                                                                             | pactjs-utils, CDCT/BDCT, integration strategy   |
+| [contract-testing](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/contract-testing.md)                             | specialized | Raw Pact patterns, publishing, verification, short-lived branch coordination, resilience, and FFI safety                                                                  | Contract testing, Pact fundamentals             |
+| [pactjs-utils-overview](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-overview.md)                   | specialized | Installation, flow decision tree, utility map, and branch coordination                                                                                                    | pactjs-utils, CDCT/BDCT, integration strategy   |
 | [pactjs-utils-mandate](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-mandate.md)                     | core        | The binding rule when `tea_use_pactjs_utils` is true: substitution table, the relevance gate before scaffolding, banned patterns, pre-emit self-check, broker degradation | Standards, contract testing, generation, review |
 | [pactjs-utils-zod-to-pact](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-zod-to-pact.md)             | specialized | `zodToPactMatchers` for consumer-curated schemas, example precedence, Pact V3 matcher mapping, anti-patterns                                                              | pactjs-utils, zod, consumer schemas, matchers   |
 | [pactjs-utils-consumer-helpers](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-consumer-helpers.md)   | specialized | Provider-state helpers: `createProviderState`, `toJsonMap`; request/response callback helpers: `setJsonBody`, `setJsonContent`                                            | pactjs-utils, consumer testing, provider state  |
-| [pactjs-utils-provider-verifier](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-provider-verifier.md) | specialized | `buildVerifierOptions`, `buildMessageVerifierOptions`, broker selectors, tagging                                                                                          | pactjs-utils, provider verification, CI         |
+| [pactjs-utils-provider-verifier](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-provider-verifier.md) | specialized | Verifier builders, scoped `consumerBranch`, provider revision metadata, branch classification                                                                             | pactjs-utils, provider verification, CI         |
 | [pactjs-utils-request-filter](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pactjs-utils-request-filter.md)       | specialized | `createRequestFilter`, `noOpRequestFilter` auth/header patterns                                                                                                           | pactjs-utils, request filter, auth injection    |
 | [pact-mcp](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pact-mcp.md)                                             | specialized | SmartBear MCP tools for provider states, review, can-i-deploy, matrix                                                                                                     | pact-mcp, broker interaction, pactflow          |
-| [pact-consumer-framework-setup](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pact-consumer-framework-setup.md)   | specialized | Consumer CDC framework scaffolding: directory layout, scripts, CI workflow, and PactV4 test patterns                                                                      | pactjs-utils, consumer CDC, framework setup     |
-| [pact-broker-webhooks](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pact-broker-webhooks.md)                     | specialized | PactFlow → GitHub `repository_dispatch` auth via a dedicated machine user and classic PAT, staleness monitoring, PAT rotation runbook                                     | pact broker, webhooks, CI operations, security  |
+| [pact-consumer-framework-setup](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pact-consumer-framework-setup.md)   | specialized | Consumer CDC scaffolding with deterministic tests, PR-only provider branch detection, and additive branch-aware `can-i-deploy`                                            | pactjs-utils, consumer CDC, framework setup     |
+| [pact-broker-webhooks](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pact-broker-webhooks.md)                     | specialized | PactFlow dispatch auth, exact provider target checkout, staleness monitoring, and PAT rotation                                                                            | pact broker, webhooks, CI operations, security  |
 | [pact-consumer-di](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/blob/main/src/agents/bmad-tea/resources/knowledge/pact-consumer-di.md)                             | extended    | Dependency-injection pattern for Pact consumer tests using real client code                                                                                               | pact, consumer, DI, contract accuracy           |
 
 **Used in:** `framework`, `test-design`, `atdd`, `automate`, `test-review`, `ci` (conditioned by `tea_use_pactjs_utils` and `tea_pact_mcp`)

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.23.4",
+  "version": "1.24.0",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",

package/src/agents/bmad-tea/resources/knowledge/contract-testing.md

@@ -458,6 +458,43 @@ jobs:
 
 ---
 
+### Coordinating Different Short-Lived Branch Names
+
+`matchingBranch: true` works only when consumer and provider branches share a
+name. Release trains often break that assumption: a consumer feature branch may
+need a provider at `release/week-32`.
+
+Treat this as two separate checks:
+
+1. **Provider selects the consumer branch.** Pass a scoped `consumer` plus
+   `consumerBranch` to `buildVerifierOptions` or
+   `buildMessageVerifierOptions`. `PACT_CONSUMER_BRANCH` is the default input.
+   The explicit `{ consumer, branch }` selector is additive to matching, main,
+   and deployed selectors.
+2. **Consumer selects the provider branch.** On PRs only, parse `Pact provider
+branch: <name>` into `PACT_PROVIDER_BRANCH`. Keep the environment-wide
+   `can-i-deploy` call, use `--ignore <provider>` for that one in-flight
+   pacticipant, then run a second `can-i-deploy` with the provider's
+   `--branch`. Both calls must fail hard.
+
+The second check is weaker than `--to-environment`: it proves compatibility
+with a branch tip, not with deployed software. Its safety comes from narrow
+scope and short lifetime. Never read the override from the merged PR on push,
+and never replace the environment check globally.
+
+Keep manual PR branch selection separate from PactFlow's
+`contract_requiring_verification_published` webhook. That event names the exact
+provider version missing a verification result. Check out its
+`providerVersionNumber`, confirm that commit belongs to
+`providerVersionBranch`, and publish with the same version and branch. Stop the
+job when the target cannot be checked out. A substitute revision produces no
+evidence for the Broker's requested target.
+
+See `pactjs-utils-provider-verifier.md`,
+`pact-consumer-framework-setup.md`, and `pact-broker-webhooks.md`.
+
+---
+
 ### Example 4: Resilience Coverage (Testing Fallback Behavior)
 
 **Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
@@ -1014,6 +1051,8 @@ Before implementing contract testing, verify:
 - [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
 - [ ] **State handlers**: Provider implements all given() states
 - [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **Short-lived branch overrides**: PR-only, scoped to one pacticipant, and
+      additive to the environment gate
 - [ ] **Webhooks configured**: Consumer changes trigger provider verification
 - [ ] **Retention policy**: Old pacts archived (keep 30 days, all production tags)
 - [ ] **Resilience tested**: Timeouts, retries, error codes in contracts
@@ -1039,25 +1078,31 @@ When `tea_use_pactjs_utils` is enabled, the following utilities replace manual b
 | Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)`                                      |
 | Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                                                          |
 | 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                                                             |
-| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                                                     |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., consumerBranch, options })`               | Handles standard selectors and a scoped named consumer branch                                              |
 | DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                                                         |
 | Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                                                                 |
+| Repeated main/master/release branch classification       | `isBreakingChangeTolerantBranch(branch)`                                          | One exact boundary for an explicit breaking-change tolerance policy                                        |
 | Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                                                            |
 | Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                                                               |
 | Hand-written matcher helper duplicating a Zod/TS type    | `zodToPactMatchers(ConsumerMovieSchema, example)`                                 | Single source of truth for response shape; consumer-curated scope keeps contracts lean and consumer-driven |
 
 See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns (`pactjs-utils-zod-to-pact.md` covers the consumer-curated schema pattern).
 
+For differently named in-flight branches, use pactjs-utils 1.2.0 or newer.
+That release adds `consumerBranch` to both verifier builders and ships the
+PR-only provider-branch detection, additive `can-i-deploy` templates, and
+`isBreakingChangeTolerantBranch`.
+
 ### PactV4 Determinism & FFI Safety (Mandatory)
 
 Four rules that together prevent both (a) non-deterministic pact generation failures that cause `Cannot change pact content for already published pact` errors at PactFlow publish, and (b) "request was expected but not received" flakes observed on Linux CI once a consumer+provider pair has more than one `.pacttest.ts` file:
 
 1. **Consumer Vitest `fileParallelism: false`** in `vitest.config.pact.ts` — prevents parallel workers from racing on the shared pact JSON. See `pact-consumer-framework-setup.md` Example 2.
-2. **Consumer Vitest `pool: 'forks'` + `poolOptions.forks.singleFork: true`** in `vitest.config.pact.ts` — same config as the provider side (`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; serialization alone (via `fileParallelism: false`) is insufficient on the default threads pool in Vitest v1. Forks + `singleFork: true` runs every pact file in one subprocess with a coherent FFI handle and eliminated a reproducible Linux-CI flake across multiple repos. Single-file consumer suites have not been observed to flake; this rule is still recommended as a future-proof. See `pact-consumer-framework-setup.md` Example 2.
+2. **Consumer Vitest `pool: 'forks'` + `poolOptions.forks.singleFork: true`** in `vitest.config.pact.ts` — same config as the provider side (`pactjs-utils-provider-verifier.md` Example 8). Best current understanding: the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; serialization alone (via `fileParallelism: false`) is insufficient on the default threads pool in Vitest v1. Forks + `singleFork: true` runs every pact file in one subprocess with a coherent FFI handle and eliminated a reproducible Linux-CI flake across multiple repos. Single-file consumer suites have not been observed to flake; this rule is still recommended as a future-proof. See `pact-consumer-framework-setup.md` Example 2.
 3. **One `addInteraction()` per `it()` block** — see `pactjs-utils-consumer-helpers.md` Example 6.
 4. **`publish-pact.sh` jq normalization** sorts interactions before publish — ensures byte-stable payload to PactFlow regardless of generator ordering quirks. See `pact-consumer-framework-setup.md` Example 4.
 
-Provider suites require the same `pool: 'forks'` + `singleFork: true` combination — see `pactjs-utils-provider-verifier.md` Example 7.
+Provider suites require the same `pool: 'forks'` + `singleFork: true` combination — see `pactjs-utils-provider-verifier.md` Example 8.
 
 ### Webhook Auth & Staleness
 

package/src/agents/bmad-tea/resources/knowledge/pact-broker-webhooks.md

@@ -9,6 +9,10 @@ Configure PactFlow webhooks to trigger provider verification in GitHub Actions v
 ### Why webhooks matter
 
 - PactFlow's `contract_requiring_verification_published` webhook is the mechanism that notifies a provider repo (via `repository_dispatch`) that a consumer has published a contract needing verification.
+- The webhook carries `${pactbroker.providerVersionNumber}` and
+  `${pactbroker.providerVersionBranch}` for the provider version missing a
+  result. The provider workflow checks out that exact registered revision
+  before publishing verification.
 - Without a working webhook, `can-i-deploy` in the consumer CI **times out** (900s) and eventually fails with `There is no verified pact between <consumer-version> and the version of <provider> currently in <env>` — even though nothing is wrong in either codebase.
 - Webhook failures are **silent by default**: PactFlow keeps emitting requests, GitHub keeps returning `401 Unauthorized`, but nothing alerts the team until a PR is blocked.
 
@@ -85,13 +89,38 @@ jobs:
       PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
       # Pulled from webhook client_payload when triggered by PactFlow:
       PACT_PAYLOAD_URL: ${{ github.event.client_payload.pact_url }}
-      GITHUB_SHA: ${{ github.event.client_payload.sha || github.sha }}
-      GITHUB_BRANCH: ${{ github.event.client_payload.branch || github.head_ref || github.ref_name }}
+      PACT_PROVIDER_VERSION: ${{ github.event.client_payload.sha }}
+      PACT_PROVIDER_BRANCH: ${{ github.event.client_payload.branch }}
     steps:
       - uses: actions/checkout@v4
         with:
-          # Check out the provider version known to the broker — this is the provider SHA PactFlow wants verified.
-          ref: ${{ github.event.client_payload.sha || github.sha }}
+          fetch-depth: 0
+      - name: Select provider revision
+        id: provider-revision
+        run: |
+          if [ -z "$PACT_PROVIDER_BRANCH" ] || [ -z "$PACT_PROVIDER_VERSION" ]; then
+            echo "Webhook payload is missing the provider branch or version."
+            exit 1
+          fi
+
+          git fetch origin -- "$PACT_PROVIDER_BRANCH"
+
+          if ! git rev-parse --verify --quiet "$PACT_PROVIDER_VERSION^{commit}" >/dev/null; then
+            echo "Provider version $PACT_PROVIDER_VERSION is unavailable."
+            exit 1
+          fi
+
+          if ! git merge-base --is-ancestor "$PACT_PROVIDER_VERSION" FETCH_HEAD; then
+            echo "Provider version $PACT_PROVIDER_VERSION is not on $PACT_PROVIDER_BRANCH."
+            exit 1
+          fi
+
+          git checkout --detach "$PACT_PROVIDER_VERSION"
+          SELECTED_VERSION="$(git rev-parse HEAD)"
+
+          echo "PACT_PROVIDER_VERSION=$SELECTED_VERSION" >> "$GITHUB_ENV"
+          echo "PACT_PROVIDER_BRANCH=$PACT_PROVIDER_BRANCH" >> "$GITHUB_ENV"
+          echo "GITHUB_BRANCH=$PACT_PROVIDER_BRANCH" >> "$GITHUB_ENV"
       - uses: actions/setup-node@v4
         with:
           node-version: 20
@@ -107,7 +136,14 @@ jobs:
 
 - `repository_dispatch` is the event type emitted by GitHub when the webhook's REST call hits `/repos/<org>/<repo>/dispatches`.
 - The `types` filter must match the webhook's `event_type` (`contract_requiring_verification_published` here).
-- Checking out the provider version known to the broker (`providerVersionNumber`) ensures verification runs against the exact provider commit PactFlow registered — not whatever is on main.
+- Check out the exact `providerVersionNumber` on `providerVersionBranch`.
+  PactFlow emits this event for each main, deployed, or released provider
+  version missing a result.
+- Verify that the commit exists and belongs to the registered branch before
+  detaching to it. A force-pushed or deleted revision fails the job and leaves
+  the requested result unknown.
+- After checkout, overwrite `PACT_PROVIDER_VERSION` with `git rev-parse HEAD`
+  and publish the result against `PACT_PROVIDER_BRANCH`.
 - `PACT_PAYLOAD_URL` makes `buildVerifierOptions` verify only the triggering pact (see `pactjs-utils-provider-verifier.md` Example 1).
 
 ### Example 3: Secret Rotation Runbook
@@ -180,6 +216,9 @@ jobs:
 - **Classic PAT, `repo` scope, no expiration** — required for `repository_dispatch`. The "no expiration" trade-off is accepted in exchange for machine-user ownership + PactFlow-secret storage + staleness monitoring.
 - **Store the PAT as a PactFlow secret** at `/settings/secrets`, reference it from the webhook via `${user.<secret-name>}`. Never inline the token.
 - **Monitor for silence** — at minimum, a daily scheduled CI job that asserts a recent verification timestamp exists for each critical consumer/provider pair.
+- **Provider targets need broker history** — publish provider verification
+  results with branch metadata. Record deployments and releases so PactFlow can
+  identify every provider version that this event must verify.
 - **Rotation is a runbook, not an emergency** — document it (see Example 3), keep it in the repo, and do a practice rotation once a year so it stays fresh.
 - **Symptom to remember**: "consumer `can-i-deploy` timeout after 900s with `There is no verified pact...`" + "provider's `contract-test-provider` workflow has no recent runs" = expired/revoked PAT. Start with Example 3.
 

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

@@ -35,8 +35,10 @@ scripts/
 
 .github/
 ├── actions/
-│   └── detect-breaking-change/
-│       └── action.yml                   # PR checkbox-driven breaking change detection
+│   ├── detect-breaking-change/
+│   │   └── action.yml                   # PR checkbox-driven breaking change detection
+│   └── detect-provider-branch/
+│       └── action.yml                   # PR-only provider branch coordination
 └── workflows/
     └── contract-test-consumer.yml       # Consumer CDC CI workflow
 ```
@@ -77,8 +79,8 @@ export default defineConfig({
 **Key Points**:
 
 - **`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`. The `publish-pact.sh` `jq` sort (Example 4) provides byte-stability at publish time.
-- **`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 across multiple repos. Vitest v2+ defaults to `forks`, but set the pool explicitly so the contract does not drift with Vitest version bumps.
-- **One `.pacttest.ts` per consumer+provider pair is the canonical pattern** — not just an observation. Two files for the same pair in one process (which `singleFork: true` guarantees) cause an FFI handle collision: the second file's `new PactV4(...)` call re-enters the FFI handle still holding stale state from the first file → "request was expected but not received" sporadically on Linux CI. The fix is structural — merge the files, not the config. `pool: 'forks'` is still required for pact JSON write safety but does NOT prevent same-pair file splits from colliding. Multiple files for **different** pairs (different consumer or provider name) are correct and safe. See Example 10 for the ✅/❌ pattern.
+- **`pool: 'forks'` + `singleFork: true` is required for multi-file consumer suites** — same config the provider side uses (`pactjs-utils-provider-verifier.md` Example 8). 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 across multiple repos. Vitest v2+ defaults to `forks`, but set the pool explicitly so the contract does not drift with Vitest version bumps.
+- **One `.pacttest.ts` per consumer+provider pair is the canonical pattern** — not just an observation. Two files for the same pair in one process (which `singleFork: true` guarantees) cause an FFI handle collision: the second file's `new PactV4(...)` call re-enters the FFI handle still holding stale state from the first file → "request was expected but not received" sporadically on Linux CI. The fix is structural — merge the files, not the config. `pool: 'forks'` is still required for pact JSON write safety but does NOT prevent same-pair file splits from colliding. Multiple files for **different** pairs (different consumer or provider name) are correct and safe. See Example 11 for the ✅/❌ pattern.
 - **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
@@ -98,13 +100,16 @@ export default defineConfig({
   "scripts": {
     "test:pact:consumer": "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",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<consumer-name> PROVIDER_PACTICIPANT=<provider-name> ./scripts/can-i-deploy.sh",
     "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
   }
 }
 ```
 
-Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+Replace `<consumer-name>` and `<provider-name>` with the Pact Broker
+pacticipant names. `PROVIDER_PACTICIPANT` scopes the optional short-lived
+provider branch override; the plain environment gate still works when no
+override is set.
 
 **Key Points**:
 
@@ -185,12 +190,33 @@ set -euo pipefail
 PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
 ENVIRONMENT="${ENVIRONMENT:-dev}"
 
-pact-broker can-i-deploy \
-    --pacticipant "$PACTICIPANT" \
-    --version="$GITHUB_SHA" \
-    --to-environment "$ENVIRONMENT" \
-    --retry-while-unknown=10 \
-    --retry-interval=30
+# PR-only override set by detect-provider-branch. Preserve the environment-wide
+# gate for every other dependency, and check the in-flight provider branch
+# separately. Both calls fail hard under set -e.
+if [ -n "${PACT_PROVIDER_BRANCH:-}" ] && [ -n "${PROVIDER_PACTICIPANT:-}" ]; then
+  pact-broker can-i-deploy \
+      --pacticipant "$PACTICIPANT" \
+      --version="$GITHUB_SHA" \
+      --to-environment "$ENVIRONMENT" \
+      --ignore "$PROVIDER_PACTICIPANT" \
+      --retry-while-unknown=10 \
+      --retry-interval=30
+
+  pact-broker can-i-deploy \
+      --pacticipant "$PACTICIPANT" \
+      --version="$GITHUB_SHA" \
+      --pacticipant "$PROVIDER_PACTICIPANT" \
+      --branch="$PACT_PROVIDER_BRANCH" \
+      --retry-while-unknown=10 \
+      --retry-interval=30
+else
+  pact-broker can-i-deploy \
+      --pacticipant "$PACTICIPANT" \
+      --version="$GITHUB_SHA" \
+      --to-environment "$ENVIRONMENT" \
+      --retry-while-unknown=10 \
+      --retry-interval=30
+fi
 ```
 
 #### `scripts/record-deployment.sh` — Record Deployment
@@ -224,6 +250,9 @@ fi
 - Use `pact-broker` directly, NOT `npx pact-broker`
 - 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)
+- A PR-only `PACT_PROVIDER_BRANCH` override is additive: the environment check
+  ignores only `PROVIDER_PACTICIPANT`, then a second check targets that
+  pacticipant's branch. `--branch` never silently replaces `--to-environment`.
 - `record-deployment` has branch guard (only records on main/master)
 - **`publish-pact.sh` normalizes interactions with `jq -S` + `sort_by(...)` before publishing** — ensures byte-stable payload to the broker regardless of generator ordering quirks.
 - 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
@@ -269,6 +298,9 @@ jobs:
       - name: Detect Pact breaking change
         uses: ./.github/actions/detect-breaking-change
 
+      - name: Detect Pact provider branch
+        uses: ./.github/actions/detect-provider-branch
+
       - name: Install dependencies
         run: npm ci
 
@@ -284,10 +316,15 @@ jobs:
       # the provider's contract-test-provider.yml workflow.
       # can-i-deploy retries while waiting for provider verification.
 
-      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
-      - name: Can I deploy consumer? (main only)
-        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+      # (4) Check deployment safety.
+      # NOTE: First-time bootstrap: if no verified contract exists on the broker yet,
+      # gate this to main only: if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+      # Once the first contract is published and verified on main, remove the main-only condition.
+      - name: Can I deploy consumer?
+        if: env.PACT_BREAKING_CHANGE != 'true'
         run: npm run can:i:deploy:consumer
+        env:
+          PACT_PROVIDER_BRANCH: ${{ env.PACT_PROVIDER_BRANCH }}
 
       # (5) Record deployment (main only)
       - name: Record consumer deployment (main only)
@@ -300,8 +337,12 @@ jobs:
 - **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. Consumer tests, publish, can-i-deploy, and record-deployment are all the same commands a developer runs locally.
 - **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
+- **`detect-provider-branch` step** runs on PR events before install and exports
+  a short-lived `PACT_PROVIDER_BRANCH` hint from the PR description
 - **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
-- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **can-i-deploy condition**: `env.PACT_BREAKING_CHANGE != 'true'` after the
+  first main contract has been published and verified. During one-time broker
+  bootstrap, gate it to main until that verification exists.
 - **Comment on (4)**: "on PRs, local verification is the gate"
 - **No upload-artifact step** — the broker is the source of truth for pact files
 - **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
@@ -377,7 +418,38 @@ runs:
 
 ---
 
-### Example 7: Consumer Test Using PactV4 Builder
+### Example 7: Detect Provider Branch Composite Action
+
+**Context**: A consumer PR needs verification against a provider branch that
+has not merged or deployed yet. Add `Pact provider branch: <name>` to the PR
+template and parse it only for `pull_request` events.
+
+```yaml
+name: 'Detect Pact Provider Branch'
+description: 'Exports a PR-only provider branch override'
+
+runs:
+  using: 'composite'
+  steps:
+    - name: Set PACT_PROVIDER_BRANCH from PR description
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const body = context.payload.pull_request.body || '';
+          const match = body.match(
+            /^[^\S\r\n]*Pact provider branch:[^\S\r\n]*(\S+)[^\S\r\n]*$/im
+          );
+          core.exportVariable('PACT_PROVIDER_BRANCH', match?.[1] || '');
+```
+
+Do not read this field from the merged PR on push. It is a coordination hint for
+one open PR, not durable deployment metadata. After merge, the normal
+`--to-environment` gate must be authoritative again.
+
+---
+
+### Example 8: Consumer Test Using PactV4 Builder
 
 **Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
 
@@ -503,7 +575,7 @@ describe('Movies API Consumer Contract', () => {
 
 ---
 
-### Example 8: Support Files
+### Example 9: Support Files
 
 #### Pact Config Factory
 
@@ -608,7 +680,7 @@ export const setJsonBody = (body: unknown) => setJsonContent({ body });
 
 ---
 
-### Example 9: .gitignore Entries
+### Example 10: .gitignore Entries
 
 **Context**: Pact-specific entries to add to `.gitignore`.
 
@@ -620,7 +692,7 @@ pact-logs/
 
 ---
 
-### Example 10: Test File Organization — One File Per Consumer+Provider Pair
+### Example 11: Test File Organization — One File Per Consumer+Provider Pair
 
 **Context**: Avoiding Pact Rust FFI handle collisions when structuring consumer test files.
 
@@ -664,7 +736,7 @@ describe('Movies API', () => {
 Before presenting the consumer CDC framework to the user, verify:
 
 - [ ] `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` is required for pact JSON write safety across files — see Example 2 Key Points for mechanism and evidence)
-- [ ] Each consumer+provider pair is covered by exactly ONE `.pacttest.ts` file — never split interactions for the same pair across multiple files (two `PactV4` instances for the same pair in one process cause FFI handle collision → "request was expected but not received" on Linux CI; `singleFork: true` does NOT prevent this — it ensures both files share one process, which guarantees the collision; see Example 10)
+- [ ] Each consumer+provider pair is covered by exactly ONE `.pacttest.ts` file — never split interactions for the same pair across multiple files (two `PactV4` instances for the same pair in one process cause FFI handle collision → "request was expected but not received" on Linux CI; `singleFork: true` does NOT prevent this — it ensures both files share one process, which guarantees the collision; see Example 11)
 - [ ] `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
 - [ ] `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 (ensures byte-stable payload to PactFlow regardless of generator ordering)
 - [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
@@ -672,6 +744,9 @@ Before presenting the consumer CDC framework to the user, verify:
 - [ ] Shell scripts use `pact-broker` not `npx pact-broker`
 - [ ] Shell scripts use `PACTICIPANT` env var pattern
 - [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `can-i-deploy.sh` keeps the environment-wide check and, only when both
+      `PACT_PROVIDER_BRANCH` and `PROVIDER_PACTICIPANT` exist, ignores that one
+      provider there and checks its branch in a second failing command
 - [ ] `record-deployment.sh` has branch guard
 - [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
 - [ ] CI workflow named `contract-test-consumer.yml`
@@ -683,6 +758,8 @@ Before presenting the consumer CDC framework to the user, verify:
 - [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
 - [ ] CI has NO upload-artifact step
 - [ ] `.github/actions/detect-breaking-change/action.yml` exists
+- [ ] `.github/actions/detect-provider-branch/action.yml` reads `Pact provider
+branch: <name>` on PR events only
 - [ ] Consumer tests use `.pacttest.ts` extension
 - [ ] Consumer tests use PactV4 `addInteraction()` builder
 - [ ] `uponReceiving()` names follow `"a request to <action> <resource> [<condition>]"` pattern and are unique within the consumer-provider pair

package/src/agents/bmad-tea/resources/knowledge/pactjs-utils-mandate.md

@@ -58,19 +58,20 @@ These are correctness rules from the per-utility fragments, not style preference
 
 ## Substitution Table
 
-| Need                                         | Raw Pact — do not emit                                                             | pactjs-utils — emit this                                                            | Level       | Fragment                            |
-| -------------------------------------------- | ---------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ----------- | ----------------------------------- |
-| Provider state on an interaction             | `.given('name', { id: 1 } as JsonMap)`, hand-cast params                           | `.given(...createProviderState({ name, params }))`                                  | REQUIRED    | `pactjs-utils-consumer-helpers.md`  |
-| Coercing params to Pact's `JsonMap`          | Manual casts, `String(date)`, `null` handling per call site                        | `toJsonMap(value)`                                                                  | REQUIRED    | `pactjs-utils-consumer-helpers.md`  |
-| PactV4 request/response builder callbacks    | Repeated inline `(b) => { b.query(...); b.headers(...); b.jsonBody(...) }` lambdas | `setJsonContent({ query?, headers?, body? })`, or `setJsonBody(body)` for body-only | REQUIRED    | `pactjs-utils-consumer-helpers.md`  |
-| HTTP provider verification options           | A hand-assembled 30-line `VerifierOptions` object                                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })`   | REQUIRED    | `pactjs-utils-provider-verifier.md` |
-| Message/Kafka provider verification options  | A second hand-assembled options object                                             | `buildMessageVerifierOptions({ ... })`                                              | REQUIRED    | `pactjs-utils-provider-verifier.md` |
-| Broker URL and consumer version selectors    | Hand-written env-var branching for local vs remote vs breaking-change flows        | `handlePactBrokerUrlAndSelectors(...)` (or let `buildVerifierOptions` read the env) | REQUIRED    | `pactjs-utils-provider-verifier.md` |
-| Provider version tags in CI                  | Hand-written branch/tag extraction per CI platform                                 | `getProviderVersionTags()`                                                          | REQUIRED    | `pactjs-utils-provider-verifier.md` |
-| Auth injection during provider verification  | A bespoke Express middleware, with its recurring `Bearer Bearer` bug               | `createRequestFilter({ tokenGenerator })`                                           | REQUIRED    | `pactjs-utils-request-filter.md`    |
-| A provider that needs no auth injection      | Omitting `requestFilter`, or an empty inline function                              | `noOpRequestFilter`                                                                 | REQUIRED    | `pactjs-utils-request-filter.md`    |
-| Response matchers where a Zod schema exists  | Hand-written `MatchersV3` trees duplicating the schema                             | `zodToPactMatchers(schema, examples?)`                                              | RECOMMENDED | `pactjs-utils-zod-to-pact.md`       |
-| Exercising the consumer inside `executeTest` | Raw `fetch(`${mockServer.url}/...`)`                                               | Inject `mockServer.url` as `baseUrl` and call the real client                       | RECOMMENDED | `pact-consumer-di.md`               |
+| Need                                         | Raw Pact — do not emit                                                               | pactjs-utils — emit this                                                            | Level       | Fragment                            |
+| -------------------------------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | ----------- | ----------------------------------- |
+| Provider state on an interaction             | `.given('name', { id: 1 } as JsonMap)`, hand-cast params                             | `.given(...createProviderState({ name, params }))`                                  | REQUIRED    | `pactjs-utils-consumer-helpers.md`  |
+| Coercing params to Pact's `JsonMap`          | Manual casts, `String(date)`, `null` handling per call site                          | `toJsonMap(value)`                                                                  | REQUIRED    | `pactjs-utils-consumer-helpers.md`  |
+| PactV4 request/response builder callbacks    | Repeated inline `(b) => { b.query(...); b.headers(...); b.jsonBody(...) }` lambdas   | `setJsonContent({ query?, headers?, body? })`, or `setJsonBody(body)` for body-only | REQUIRED    | `pactjs-utils-consumer-helpers.md`  |
+| HTTP provider verification options           | A hand-assembled 30-line `VerifierOptions` object                                    | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })`   | REQUIRED    | `pactjs-utils-provider-verifier.md` |
+| Message/Kafka provider verification options  | A second hand-assembled options object                                               | `buildMessageVerifierOptions({ ... })`                                              | REQUIRED    | `pactjs-utils-provider-verifier.md` |
+| Broker URL and consumer version selectors    | Hand-written env branching for local, remote, breaking-change, or named-branch flows | `handlePactBrokerUrlAndSelectors(...)` (or let `buildVerifierOptions` read the env) | REQUIRED    | `pactjs-utils-provider-verifier.md` |
+| Provider version tags in CI                  | Hand-written branch/tag extraction per CI platform                                   | `getProviderVersionTags()`                                                          | REQUIRED    | `pactjs-utils-provider-verifier.md` |
+| Breaking-change tolerant branch check        | Repeated `main` / `master` / `release/` string logic                                 | `isBreakingChangeTolerantBranch(branch)`                                            | REQUIRED    | `pactjs-utils-provider-verifier.md` |
+| Auth injection during provider verification  | A bespoke Express middleware, with its recurring `Bearer Bearer` bug                 | `createRequestFilter({ tokenGenerator })`                                           | REQUIRED    | `pactjs-utils-request-filter.md`    |
+| A provider that needs no auth injection      | Omitting `requestFilter`, or an empty inline function                                | `noOpRequestFilter`                                                                 | REQUIRED    | `pactjs-utils-request-filter.md`    |
+| Response matchers where a Zod schema exists  | Hand-written `MatchersV3` trees duplicating the schema                               | `zodToPactMatchers(schema, examples?)`                                              | RECOMMENDED | `pactjs-utils-zod-to-pact.md`       |
+| Exercising the consumer inside `executeTest` | Raw `fetch(`${mockServer.url}/...`)`                                                 | Inject `mockServer.url` as `baseUrl` and call the real client                       | RECOMMENDED | `pact-consumer-di.md`               |
 
 `zodToPactMatchers` is RECOMMENDED because it needs a Zod schema to exist. Where the project has one, derive the matchers from it rather than maintaining a parallel matcher tree. Where it does not, write matchers from provider scrutiny and say so.
 
@@ -82,6 +83,11 @@ When this mandate is active, these are defects in generated or reviewed code:
 
 - `.given('state name', someObject as JsonMap)` — a hand-cast provider state where `createProviderState` applies.
 - A literal `VerifierOptions` object passed to `new Verifier(...)`, where `buildVerifierOptions` applies.
+- Hand-built `{ branch: process.env.PACT_CONSUMER_BRANCH }` selectors where the
+  builder's scoped `consumer` + `consumerBranch` inputs apply.
+- Hand-written `branch === 'main' || branch === 'master' ||
+branch.startsWith('release/')` checks where
+  `isBreakingChangeTolerantBranch` applies.
 - A bespoke `requestFilter` middleware that prefixes a bearer token by hand.
 - Repeated inline PactV4 builder lambdas that `setJsonContent` or `setJsonBody` would replace.
 - Raw `fetch` inside `executeTest` in a project whose consumer client is importable, with no note saying why.
@@ -159,6 +165,8 @@ await new Verifier(
     provider: 'SampleMoviesAPI',
     port: '3001',
     includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+    consumer: 'movie-web',
+    consumerBranch: process.env.PACT_CONSUMER_BRANCH,
     stateHandlers,
     requestFilter: createRequestFilter({ tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token' }),
   }),
@@ -179,6 +187,13 @@ Any `yes` is a blocker.
 6. Does `executeTest` call raw `fetch` while the consumer client is importable, with no stated reason?
 7. Is any response matcher derived from consumer-side types rather than provider source, OpenAPI, or broker data?
 8. Is any interaction missing its `// Provider endpoint:` comment?
+9. Does provider verification hand-build an explicit consumer branch selector,
+   or set `consumerBranch` without a scoped `consumer`?
+10. Does a breaking-change catch hand-roll tolerant branch classification
+    instead of `isBreakingChangeTolerantBranch`, or check breaking-change
+    tolerance before rejecting a "no pacts found" result that occurred with
+    an explicit `PACT_CONSUMER_BRANCH` set (letting a typo masquerade as a
+    tolerated breaking change)?
 
 Fix, or record a deviation. Do not emit unresolved.