ma-agents 3.9.0 → 3.12.0

package/lib/bmad-cache/tea/README.md

@@ -216,17 +216,28 @@ See `CONTRIBUTING.md` for guidelines.
 
 ## Publishing TEA to NPM
 
-TEA uses an automated release workflow that handles versioning, metadata sync, tagging, NPM publishing, and GitHub releases.
+TEA uses an automated publish workflow modeled after the main `BMAD-METHOD` repo. It supports:
+
+- `next` prereleases published automatically from `main`
+- manual stable releases on the `latest` dist-tag
+- trusted npm publishing (no `NPM_TOKEN` secret)
+- metadata sync for `package.json`, `package-lock.json`, and `.claude-plugin/marketplace.json`
 
 ### Prerequisites (One-Time Setup)
 
-1. **NPM Token Configuration:**
-   - Generate NPM automation token: [npmjs.com/settings/tokens](https://www.npmjs.com/settings/your-username/tokens)
-   - Add to GitHub Secrets: `Settings` → `Secrets and variables` → `Actions` → `New repository secret`
-   - Name: `NPM_TOKEN`
-   - Value: [your token]
+1. **npm Trusted Publishing:**
+   - In npm package settings for `bmad-method-test-architecture-enterprise`, configure Trusted Publishers for this GitHub repository
+   - Allow publishes from the `bmad-code-org/bmad-method-test-architecture-enterprise` repo and the `.github/workflows/publish.yaml` workflow
+   - GitHub Actions must be able to request an OIDC token (`id-token: write`), which the workflow already does
+
+2. **GitHub App Secrets for Stable Releases:**
+   - Add `RELEASE_APP_ID`
+   - Add `RELEASE_APP_PRIVATE_KEY`
+   - Install the corresponding GitHub App on this repository with contents write access
+   - If `main` is protected, ensure the app is allowed to push the release commit and tag
+   - These are used only for manual stable releases so the workflow can push the version bump commit and tag back to `main`
 
-2. **Verify Package Configuration:**
+3. **Verify Package Configuration:**
    ```bash
    # Check package.json settings
    cat package.json | grep -A 3 "publishConfig"
@@ -242,71 +253,61 @@ TEA uses an automated release workflow that handles versioning, metadata sync, t
 
 #### Option 1: Using npm Scripts (Recommended)
 
-From your local terminal after merging to the release branch you want to publish, typically `main`:
+From your local terminal after merging to `main`:
 
 ```bash
-# Beta release (first release or testing)
-npm run release:beta
-
-# Alpha release (early testing)
-npm run release:alpha
+# Publish the next prerelease from current main
+npm run release:next
 
-# Patch release (bug fixes)
+# Publish a stable patch release
 npm run release:patch
 
-# Minor release (new features, backwards compatible)
+# Publish a stable minor release
 npm run release:minor
 
-# Major release (breaking changes)
+# Publish a stable major release
 npm run release:major
 ```
 
 #### Option 2: Manual Workflow Trigger
 
 1. Go to **Actions** tab in GitHub
-2. Click **"Manual Release"** workflow
+2. Click **"Publish"** workflow
 3. Click **"Run workflow"**
 4. Choose the branch to release, typically `main`
-5. Select version bump type (alpha, beta, patch, minor, major)
-6. Click **"Run workflow"**
+5. Select channel:
+   - `next` for a prerelease publish
+   - `latest` for a stable release
+6. If using `latest`, choose the bump type (`patch`, `minor`, `major`)
+7. Click **"Run workflow"**
 
 ### What Happens Automatically
 
 The workflow performs these steps:
 
 1. ✅ **Validation**: Runs the full `npm test` suite, including schema checks, install tests, knowledge checks, linting, markdown linting, formatting, and release metadata validation
-2. ✅ **Version Bump**: Updates `package.json`, `package-lock.json`, and `.claude-plugin/marketplace.json`
-   - `beta`: 1.12.3 → 1.12.4-beta.0
-   - `alpha`: 1.12.3 → 1.12.4-alpha.0
-   - `patch`: 1.12.3 → 1.12.4
-   - `minor`: 1.12.3 → 1.13.0
-   - `major`: 1.12.3 → 2.0.0
-3. ✅ **Commit**: Creates version bump commit
-4. ✅ **Tag**: Creates git tag (e.g., v1.12.4-beta.0)
-5. ✅ **Publish**: Publishes to NPM registry
-   - Alpha → dist-tag `alpha` (`npm install bmad-method-test-architecture-enterprise@alpha`)
-   - Beta → dist-tag `beta` (`npm install bmad-method-test-architecture-enterprise@beta`)
-   - Stable → dist-tag `latest` (`npm install bmad-method-test-architecture-enterprise`)
-6. ✅ **Push**: Pushes the version bump commit back to the selected branch when permitted, and always pushes the tag
-7. ✅ **GitHub Release**: Creates release with auto-generated notes
-8. ✅ **Summary**: Displays installation instructions and distribution links
-
-### Version Bump Strategy
-
-**For TEA Module:**
-
-- **Beta (`1.12.x-beta.x`)**: Release candidate testing on the next patch line
-- **Alpha (`1.12.x-alpha.x`)**: Early development and experimental validation
-- **Patch (`1.12.x`)**: Bug fixes, no breaking changes
-- **Minor (`1.x.0`)**: New features, backwards compatible
-- **Major (`x.0.0`)**: Breaking changes
+2. ✅ **Version Bump**:
+   - `next`: derives the next prerelease version and publishes it with dist-tag `next`
+   - `latest`: bumps the stable version (`patch`, `minor`, or `major`)
+3. ✅ **Metadata Sync**: Updates `.claude-plugin/marketplace.json` to match the package version before publishing
+4. ✅ **Publish**: Publishes to npm with provenance enabled
+   - `next` → `npm publish --tag next --provenance`
+   - `latest` → `npm publish --tag latest --provenance`
+5. ✅ **Stable Release Finalization**: For `latest`, creates a version bump commit, tags it, pushes it to `main`, and creates a GitHub Release
+
+### Channel Strategy
+
+- **`next`**: prerelease channel for the newest merged changes
+- **`latest`**: stable channel for intentional releases
+- **`patch`**: bug fixes, no breaking changes
+- **`minor`**: new features, backwards compatible
+- **`major`**: breaking changes
 
 **Recommended Release Path:**
 
-1. `1.12.3` → `1.12.4-beta.0` (first beta)
-2. Test beta with early adopters
-3. `1.12.4-beta.0` → `1.12.4-beta.1` (fixes)
-4. When stable: `1.12.4-beta.1` → `1.12.4`
+1. Merge releasable work to `main`
+2. Let `next` publish for early validation
+3. When ready, cut a stable `latest` release via `patch`, `minor`, or `major`
 
 ### Verify Publication
 
@@ -314,6 +315,7 @@ The workflow performs these steps:
 
 ```bash
 npm view bmad-method-test-architecture-enterprise
+npm view bmad-method-test-architecture-enterprise dist-tags
 ```
 
 **Install TEA:**
@@ -337,24 +339,31 @@ If you need to unpublish a version:
 
 ```bash
 # Unpublish specific version (within 72 hours)
-npm unpublish bmad-method-test-architecture-enterprise@1.12.4-beta.0
+npm unpublish bmad-method-test-architecture-enterprise@1.13.2-next.0
 
 # Deprecate version (preferred for older releases)
-npm deprecate bmad-method-test-architecture-enterprise@1.12.4-beta.0 "Use version X.Y.Z instead"
+npm deprecate bmad-method-test-architecture-enterprise@1.13.2-next.0 "Use version X.Y.Z instead"
 ```
 
 ### Troubleshooting
 
-**"NPM_TOKEN not found":**
+**Trusted publishing failed:**
 
-- Verify secret is set: GitHub repo → Settings → Secrets and variables → Actions
-- Secret name must be exactly: `NPM_TOKEN`
+- Verify npm Trusted Publishing is configured for this repository and workflow
+- Verify the workflow has `id-token: write`
+- Confirm the publish is running from the canonical repository, not a fork
 
 **"Package already exists":**
 
 - Check if package name is already taken on NPM
 - Update `name` in `package.json` if needed
 
+**"Version push failed":**
+
+- Verify `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` are configured
+- Verify the GitHub App is installed on this repository with contents write access
+- If branch protection is enabled on `main`, verify the app is allowed to push the release commit and tag
+
 **"Tests failed":**
 
 - Fix failing tests before release
@@ -362,9 +371,9 @@ npm deprecate bmad-method-test-architecture-enterprise@1.12.4-beta.0 "Use versio
 
 **"Git push failed (protected branch)":**
 
-- This is expected for a protected release branch
-- The tag and version bump are still created
-- You may need to manually merge the version bump commit
+- This is not expected once the release GitHub App is configured correctly
+- Verify branch protection allows the app to push the release commit and tag
+- If needed, create the GitHub Release manually after resolving the app permissions
 
 ### Release Checklist
 
@@ -375,7 +384,8 @@ Before releasing:
 - [ ] CHANGELOG.md updated
 - [ ] No uncommitted changes
 - [ ] On `main` branch
-- [ ] NPM token configured in GitHub Secrets
+- [ ] npm Trusted Publishing configured
+- [ ] `RELEASE_APP_ID` and `RELEASE_APP_PRIVATE_KEY` configured
 - [ ] Package name available on NPM
 
 After releasing:

package/lib/bmad-cache/tea/_git_preserved/packed-refs

@@ -1,2 +1,2 @@
 # pack-refs with: peeled fully-peeled sorted 
-3016dd0390208ef4c9b68841252f6db07fb8805e refs/remotes/origin/main
+b0ee2a5128d0f0b9f32c30a0017722a846518349 refs/remotes/origin/main

package/lib/bmad-cache/tea/_git_preserved/refs/heads/main

@@ -1 +1 @@
-3016dd0390208ef4c9b68841252f6db07fb8805e
+b0ee2a5128d0f0b9f32c30a0017722a846518349

package/lib/bmad-cache/tea/_git_preserved/shallow

@@ -1 +1 @@
-3016dd0390208ef4c9b68841252f6db07fb8805e
+b0ee2a5128d0f0b9f32c30a0017722a846518349

package/lib/bmad-cache/tea/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.13.1",
+  "version": "1.15.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "bmad-method-test-architecture-enterprise",
-      "version": "1.13.1",
+      "version": "1.15.1",
       "license": "MIT",
       "dependencies": {
         "@clack/prompts": "^0.11.0",

package/lib/bmad-cache/tea/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.13.1",
+  "version": "1.15.1",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -33,11 +33,10 @@
     "lint:fix": "eslint . --fix",
     "lint:md": "markdownlint-cli2 '**/*.md'",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "release:alpha": "gh workflow run manual-release.yaml -f version_bump=alpha",
-    "release:beta": "gh workflow run manual-release.yaml -f version_bump=beta",
-    "release:major": "gh workflow run manual-release.yaml -f version_bump=major",
-    "release:minor": "gh workflow run manual-release.yaml -f version_bump=minor",
-    "release:patch": "gh workflow run manual-release.yaml -f version_bump=patch",
+    "release:major": "gh workflow run publish.yaml -f channel=latest -f bump=major",
+    "release:minor": "gh workflow run publish.yaml -f channel=latest -f bump=minor",
+    "release:next": "gh workflow run publish.yaml -f channel=next",
+    "release:patch": "gh workflow run publish.yaml -f channel=latest -f bump=patch",
     "test": "npm run test:schemas && npm run test:install && npm run test:knowledge && npm run test:release-metadata && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
     "test:coverage": "c8 npm test",
     "test:install": "node test/test-installation-components.js",

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

@@ -167,8 +167,7 @@ describe('User API Contract', () => {
 ```json
 {
   "scripts": {
-    "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",
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
     "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
   }
 }
@@ -1056,7 +1055,7 @@ Four rules that together prevent both (a) non-deterministic pact generation fail
 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 on two repos (`pactjs-utils`, `seon-mcp-server`). 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. **Determinism gate** runs the consumer suite N times and fails on byte-different pact JSON before publish — see `pact-consumer-framework-setup.md` Example 10 (`scripts/check-pact-determinism.sh`).
+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.
 

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

@@ -76,9 +76,9 @@ 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`. See Example 10 for the determinism gate that enforces byte-stability across re-runs.
+- **`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 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.
+- **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.
 - **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
@@ -96,8 +96,7 @@ export default defineConfig({
 ```json
 {
   "scripts": {
-    "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",
+    "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",
     "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
@@ -109,8 +108,6 @@ 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
@@ -139,7 +136,7 @@ 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 (with defense-in-depth normalization)
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
 
 ```bash
 #!/bin/bash
@@ -147,9 +144,8 @@ export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
 #
 # 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.
+# if the PactV4 generator produces ordering drift between runs. Ensures "Cannot change pact content"
+# from PactFlow never fires on ordering-only changes.
 #
 # 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
@@ -229,7 +225,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.
+- **`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
 
 ---
@@ -276,8 +272,8 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      # (1) Generate pact files — runs the determinism gate (3 runs + byte-stable check via jq)
-      - name: Consumer pact tests (determinism gate)
+      # (1) Generate pact files
+      - name: Run consumer contract tests
         run: npm run test:pact:consumer
 
       # (2) Publish pacts to broker (publish-pact.sh also normalizes interaction order as defense-in-depth)
@@ -301,8 +297,7 @@ 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.
+- **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
 - **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
@@ -625,89 +620,42 @@ pact-logs/
 
 ---
 
-### Example 10: Determinism Gate Script (Primary Defense)
+### Example 10: Test File Organization — One File Per Consumer+Provider Pair
 
-**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.
+**Context**: Avoiding Pact Rust FFI handle collisions when structuring consumer test files.
 
-**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}"
+**Rule**: Every consumer+provider pair maps to exactly one `.pacttest.ts` file. Never split interactions for the same pair across multiple files.
 
-TMP_DIR="$(mktemp -d)"
-trap 'rm -rf "$TMP_DIR"' EXIT
+**Root cause**: The Pact Rust FFI maintains one handle per consumer+provider pair per process. With `singleFork: true` (all files run sequentially in one forked process), two files for the same pair access the same FFI handle back-to-back. The second file's `new PactV4({ consumer, provider })` call re-enters the handle still holding stale interaction state from the first file. The first test in the second file starts the mock server in this corrupted state — "request was expected but not received" results, sporadic and Linux-CI-only (execution order differs between environments).
 
-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}'
-}
+**Evidence**: In `pactjs-utils`, `movies-read.pacttest.ts` and `movies-write.pacttest.ts` both used `consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI'`. The vitest config and CI workflow were correct throughout. The fix was merging the two files into `movies.pacttest.ts`. The config was not changed.
 
-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."
+```typescript
+// ❌ WRONG — same consumer+provider pair split across two files
+// movies-read.pacttest.ts
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Read Operations', () => { /* 4 tests: GET /movies, GET /movies/:id */ })
+
+// movies-write.pacttest.ts  ← second PactV4 for the SAME pair = FFI handle collision
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Write Operations', () => { /* 5 tests: POST, PUT, DELETE */ })
+
+// ✅ RIGHT — one file per consumer+provider pair, describe blocks for organization
+// movies.pacttest.ts
+const pact = new PactV4({ consumer: 'SampleAppConsumer', provider: 'SampleMoviesAPI', ... })
+describe('Movies API', () => {
+  describe('Read Operations', () => { /* 4 tests */ })
+  describe('Write Operations', () => { /* 5 tests */ })
+})
 ```
 
 **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.
+- **File = contract**: A `.pacttest.ts` file represents one consumer+provider contract. One contract = one file.
+- **Describe blocks, not files**: Organize by operation type (`Read Operations`, `Write Operations`), resource, or feature — always within one file per pair.
+- **Different pairs = different files**: `ServiceA / BackendAPI` and `ServiceA / AuthAPI` are two contracts and correctly use two separate files. This rule only forbids splitting ONE pair.
+- **`singleFork: true` is not a fix for this**: It ensures correct pact JSON write semantics across files, but when two files share a pair it actually guarantees the FFI collision (both land in the same process). Without it you'd get file-write races instead. Neither is safe. The fix is one file per pair.
+- **Naming convention**: `{domain}.pacttest.ts` when one domain maps to one pair. `{consumer-kebab}-{provider-kebab}.pacttest.ts` when the filename must be self-describing about which pair it covers.
 
 ---
 
@@ -715,12 +663,11 @@ echo "✅ Pact output is byte-stable across $RUNS runs."
 
 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` 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` 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)
 - [ ] `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/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`)
 - [ ] 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
@@ -730,7 +677,7 @@ 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 step (1) generates pact files (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

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

@@ -260,10 +260,9 @@ it.each([
 
 **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`.
+- **This rule stacks with two MANDATORY vitest settings and one file-organization rule. All four address different failure modes; none substitutes for the others**: (1) `fileParallelism: false` — prevents parallel workers racing on the shared pact JSON file; (2) `pool: 'forks'` with `singleFork: true` — required for pact JSON write safety across multiple files; (3) **one `.pacttest.ts` per consumer+provider pair** — `singleFork: true` keeps all files in one process, so two files for the same pair produce an FFI handle collision ("request was expected but not received" on Linux CI, sporadic); (4) one-interaction-per-`it()` (this rule) — prevents the FFI from dropping interactions within a single test body. See `pact-consumer-framework-setup.md` Example 10 for the file-organization ✅/❌ pattern.
+- Symptom of violating this rule: the pact file is byte-different between otherwise-identical runs; 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
 
@@ -278,13 +277,13 @@ it.each([
 - **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.
+- **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.
 
 ## Related Fragments
 
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
 - `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
+- `pact-consumer-framework-setup.md` — Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true` config and CI wiring
 - `contract-testing.md` — foundational patterns with raw Pact.js
 
 ## Anti-Patterns
@@ -375,6 +374,6 @@ it('returns empty list', async () => {
 });
 ```
 
-See Example 6 above for the full rationale and the determinism gate that enforces this rule.
+See Example 6 above for the full rationale.
 
 _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-provider-verifier.md

@@ -296,7 +296,7 @@ export default defineConfig({
 - `pactjs-utils-overview.md` — installation, decision tree, design philosophy
 - `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-consumer-framework-setup.md` — consumer-side framework setup, Vitest `fileParallelism: false`, CI wiring
 - `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
 

package/lib/bmad-cache/tea/src/agents/bmad-tea/resources/tea-index.csv

@@ -38,7 +38,7 @@ pactjs-utils-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderStat
 pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions; vitest pool:forks + singleFork for FFI safety (same rule applies to consumer and provider)","pactjs-utils,provider,consumer,contract-testing,pact,api,backend,ci,vitest,ffi",specialized,knowledge/pactjs-utils-provider-verifier.md
 pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
 pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
-pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config with fileParallelism:false + pool:forks + singleFork:true (FFI safety), determinism gate (check-pact-determinism.sh), jq-normalized publishing, 1:1 local/CI parity, PactV4 patterns","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts,determinism,jq,pactv4,ffi",specialized,knowledge/pact-consumer-framework-setup.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config with fileParallelism:false + pool:forks + singleFork:true (FFI safety), one-file-per-consumer+provider-pair rule (FFI handle collision prevention), jq-normalized publishing, 1:1 local/CI parity, PactV4 patterns","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts,jq,pactv4,ffi,file-organization,one-file-per-pair",specialized,knowledge/pact-consumer-framework-setup.md
 pact-broker-webhooks,Pact Broker Webhooks,"PactFlow → GitHub repository_dispatch auth via dedicated machine user + classic PAT (repo scope, no expiration) + PactFlow secret; staleness monitoring and PAT rotation runbook","pact,pactflow,broker,webhooks,github,auth,pat,ci,operations,security",specialized,knowledge/pact-broker-webhooks.md
 adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
 playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md