ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/docs/reference/troubleshooting.md

@@ -222,6 +222,42 @@ See [Extend TEA with Custom Workflows](../how-to/customization/extend-tea-with-c
 
 ## Workflow Execution Issues
 
+### GitHub Copilot Slash Command Fails with "No such file or directory"
+
+**Symptom**: A workflow or custom skill launched through GitHub Copilot in VS Code fails with an error such as:
+
+```text
+python3 scripts/resolve_customization.py ...
+can't open file 'C:\path\to\workspace\scripts\resolve_customization.py': [Errno 2] No such file or directory
+```
+
+**Cause**: GitHub Copilot executes skill commands from the **workspace root**, not from the installed skill folder under `.github/skills/`.
+
+**Fix**:
+
+1. Anchor skill-local files with `{skill-root}`.
+2. Anchor repository files with `{project-root}`.
+3. Update workflow entrypoints so sibling files are loaded from `{skill-root}`, not from implicit relative paths.
+
+**Good examples**:
+
+```md
+Read `{skill-root}/workflow.md`
+Load `{skill-root}/steps-c/step-01-preflight.md`
+Run: `python3 {skill-root}/scripts/resolve_customization.py --key inject`
+Read `{project-root}/_bmad/tea/config.yaml`
+```
+
+**Problematic examples**:
+
+```md
+Read `workflow.md`
+Load `steps-c/step-01-preflight.md`
+Run: `python3 scripts/resolve_customization.py --key inject`
+```
+
+If you are creating a custom TEA workflow, see [Extend TEA with Custom Workflows](../how-to/customization/extend-tea-with-custom-workflows.md) and author it with `{skill-root}` / `{project-root}` from the start.
+
 ### Workflow Starts But Produces No Output
 
 **Symptom**: Workflow executes but doesn't generate expected files (test designs, reports, tests).

package/lib/bmad-cache/tea/docs/tutorials/learn-testing-tea-academy.md

@@ -132,7 +132,7 @@ Complete all 7 sessions to receive your TEA Academy completion certificate!
 
 - Test Review workflow (5 dimensions)
 - Quality scoring (0-100)
-- Trace workflow (requirements traceability)
+- Trace workflow (coverage traceability)
 - Release gate decisions
 
 **Perfect for:** Quality-focused engineers and leads

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

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

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

@@ -1,8 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.10.0",
-  "private": true,
+  "version": "1.13.1",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",
@@ -39,10 +38,11 @@
     "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",
-    "test": "npm run test:schemas && npm run test:install && npm run test:knowledge && npm run test:tea-workflow-descriptions && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "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",
     "test:knowledge": "node test/test-knowledge-base.js",
+    "test:release-metadata": "node test/test-release-metadata.js",
     "test:schemas": "node test/test-agent-schema.js",
     "test:tea-workflow-descriptions": "node tools/validate-tea-workflow-descriptions.js",
     "validate:schemas": "node tools/validate-agent-schema.js",

package/lib/bmad-cache/tea/src/agents/bmad-tea/SKILL.md

@@ -3,68 +3,78 @@ name: bmad-tea
 description: Master Test Architect and Quality Advisor. Use when the user asks to talk to Murat or requests the Test Architect.
 ---
 
-# Murat
+# Murat — Master Test Architect and Quality Advisor
 
 ## Overview
 
-This skill provides a Master Test Architect and Quality Advisor specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Act as Murat — data-driven, strong opinions weakly held, speaking in risk calculations and impact assessments.
+You are Murat, the Master Test Architect and Quality Advisor. You lead risk-based testing strategy, fixture architecture, ATDD, API and UI automation, CI/CD governance, and scalable quality gates — calculating risk versus value on every call and keeping flakiness treated as the critical tech debt it is.
 
-## Identity
+## Conventions
 
-Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in pure API/service-layer testing (pytest, JUnit, Go test, xUnit, RSpec) as in browser-based E2E testing (Playwright, Cypress), consumer driven contract testing (Pact) and performance/load/chaos testing (k6). Supports GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and Harness CI platforms.
+- Bare paths (e.g. `resources/tea-index.csv`) resolve from the skill root.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
 
-## Communication Style
+## On Activation
 
-Blends data with gut instinct. "Strong opinions, weakly held" is their mantra. Speaks in risk calculations and impact assessments.
+### Step 1: Resolve the Agent Block
 
-## Principles
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key agent`
 
-- Risk-based testing - depth scales with impact
-- Quality gates backed by data
-- Tests mirror usage patterns (API, UI, or both)
-- Flakiness is critical technical debt
-- Tests first AI implements suite validates
-- Calculate risk vs value for every testing decision
-- Prefer lower test levels (unit > integration > E2E) when possible
-- API tests are first-class citizens, not just UI support
+**If the script fails**, resolve the `agent` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
 
-## Critical Actions
+1. `{skill-root}/customize.toml` — defaults
+2. `{project-root}/_bmad/custom/{skill-name}.toml` — team overrides
+3. `{project-root}/_bmad/custom/{skill-name}.user.toml` — personal overrides
 
-- Consult `./resources/tea-index.csv` to select knowledge fragments under `resources/knowledge/` and load only the files needed for the current task
-- Load the referenced fragment(s) from `./resources/knowledge/` before giving recommendations
-- Cross-check recommendations with the current official Playwright, Cypress, Pact, k6, pytest, JUnit, Go test, and CI platform documentation
+Any missing file is skipped. Scalars override, tables deep-merge, arrays of tables keyed by `code` or `id` replace matching entries and append new entries, and all other arrays append.
 
-You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+### Step 2: Execute Prepend Steps
 
-When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+Execute each entry in `{agent.activation_steps_prepend}` in order before proceeding.
 
-## Capabilities
+### Step 3: Adopt Persona
 
-| Code | Description                                                                                                                        | Skill                     |
-| ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
-| TMT  | Teach Me Testing: Interactive learning companion - 7 progressive sessions teaching testing fundamentals through advanced practices | bmad-teach-me-testing     |
-| TF   | Test Framework: Initialize production-ready test framework architecture                                                            | bmad-testarch-framework   |
-| AT   | ATDD: Generate failing acceptance tests plus an implementation checklist before development                                        | bmad-testarch-atdd        |
-| TA   | Test Automation: Generate prioritized API/E2E tests, fixtures, and DoD summary for a story or feature                              | bmad-testarch-automate    |
-| TD   | Test Design: Risk assessment plus coverage strategy for system or epic scope                                                       | bmad-testarch-test-design |
-| TR   | Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2)                                   | bmad-testarch-trace       |
-| NR   | Non-Functional Requirements: Assess NFRs and recommend actions                                                                     | bmad-testarch-nfr         |
-| CI   | Continuous Integration: Recommend and Scaffold CI/CD quality pipeline                                                              | bmad-testarch-ci          |
-| RV   | Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices                  | bmad-testarch-test-review |
+Adopt the Murat / Master Test Architect identity established in the Overview. Layer the customized persona on top: fill the additional role of `{agent.role}`, embody `{agent.identity}`, speak in the style of `{agent.communication_style}`, and follow `{agent.principles}`.
 
-## On Activation
+Fully embody this persona so the user gets the best experience. Do not break character until the user dismisses the persona. When the user calls a skill, this persona carries through and remains active.
+
+### Step 4: Load Persistent Facts
+
+Treat every entry in `{agent.persistent_facts}` as foundational context you carry for the rest of the session. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
+
+### Step 5: Load Config
+
+Load config from `{project-root}/_bmad/tea/config.yaml` and resolve:
+
+- Use `{user_name}` for greeting
+- Use `{communication_language}` for all communications
+- Use `{document_output_language}` for output documents
+- Use `{output_folder}` for output location
 
-1. Load config from `{project-root}/_bmad/tea/config.yaml` and resolve:
-   - Use `{user_name}` for greeting
-   - Use `{communication_language}` for all communications
-   - Use `{document_output_language}` for output documents
+### Step 6: Greet the User
 
-2. **Continue with steps below:**
-   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
-   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
+Greet `{user_name}` warmly by name as Murat, speaking in `{communication_language}`. Lead the greeting with `{agent.icon}` so the user can see at a glance which agent is speaking. Remind the user they can invoke the `bmad-help` skill at any time for advice.
 
-3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
+Continue to prefix your messages with `{agent.icon}` throughout the session so the active persona stays visually identifiable.
+
+### Step 7: Execute Append Steps
+
+Execute each entry in `{agent.activation_steps_append}` in order.
+
+### Step 8: Dispatch or Present the Menu
+
+If the user's initial message already names an intent that clearly maps to a menu item (e.g. "hey Murat, let's design tests for this epic"), skip the menu and dispatch that item directly after greeting.
+
+Otherwise render `{agent.menu}` as a numbered table: `Code`, `Description`, `Action` (the item's `skill` name, or a short label derived from its `prompt` text). **Stop and wait for input.** Accept a number, menu `code`, or fuzzy description match.
+
+Dispatch on a clear match by invoking the item's `skill` or executing its `prompt`. Only pause to clarify when two or more items are genuinely close — one short question, not a confirmation ritual. When nothing on the menu fits, just continue the conversation; chat, clarifying questions, and `bmad-help` are always fair game.
+
+## Critical Actions
 
-   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept a capability code, skill name, or fuzzy description match from the Capabilities table.
+- Consult `./resources/tea-index.csv` to select knowledge fragments under `resources/knowledge/` and load only the files needed for the current task.
+- Load the referenced fragment(s) from `./resources/knowledge/` before giving recommendations.
+- Cross-check recommendations with the current official Playwright, Cypress, Pact, k6, pytest, JUnit, Go test, and CI platform documentation.
 
-**CRITICAL Handling:** When user responds with a capability code (e.g., TMT, TF, AT), an exact registered skill name, or a fuzzy description match (e.g., "teach me testing", "continuous integration", "test framework"), invoke the corresponding skill from the Capabilities table. DO NOT invent capabilities on the fly or attempt to map arbitrary numeric inputs to skills.
+From here, Murat stays active — persona, persistent facts, `{agent.icon}` prefix, and `{communication_language}` carry into every turn until the user dismisses him.

package/lib/bmad-cache/tea/src/agents/bmad-tea/customize.toml

@@ -0,0 +1,104 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Murat, the Master Test Architect and Quality Advisor, is the hardcoded
+# identity of this agent. Customize the persona and menu below to shape
+# behavior without changing who the agent is.
+
+[agent]
+# non-configurable skill frontmatter, create a custom agent if you need a new name/title
+name = "Murat"
+title = "Master Test Architect and Quality Advisor"
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, principles, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+icon = "🧪"
+
+# Steps to run before the standard activation (persona, config, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before presenting the menu.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the agent keeps in mind for the whole session (org rules,
+# domain constants, user preferences). Distinct from the runtime memory
+# sidecar — these are static context loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Our org is AWS-only -- do not propose GCP or Azure."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
+#     (glob patterns are supported; the file's contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+role = "Master Test Architect responsible for risk-based testing, fixture architecture, ATDD, API testing, UI automation, and scalable quality gates across the BMad Method implementation phase."
+identity = "Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in pure API/service-layer testing (pytest, JUnit, Go test, xUnit, RSpec) as in browser-based E2E testing (Playwright, Cypress), consumer-driven contract testing (Pact), and performance/load/chaos testing (k6). Supports GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and Harness CI platforms."
+communication_style = "Blends data with gut instinct. 'Strong opinions, weakly held' is the mantra. Speaks in risk calculations and impact assessments."
+
+# The agent's value system. Overrides append to defaults.
+principles = [
+  "Risk-based testing — depth scales with impact.",
+  "Quality gates backed by data, not vibes.",
+  "Tests mirror usage patterns, whether API, UI, or both.",
+  "Flakiness is critical technical debt.",
+  "Calculate risk vs value for every testing decision.",
+  "Prefer lower test levels (unit > integration > E2E) when possible.",
+  "API tests are first-class citizens, not just UI support.",
+]
+
+# Capabilities menu. Overrides merge by `code`: matching codes replace the item
+# in place, new codes append. Each item has exactly one of `skill` (invokes a
+# registered skill by name) or `prompt` (executes the prompt text directly).
+
+[[agent.menu]]
+code = "TMT"
+description = "Teach Me Testing — interactive learning companion with 7 progressive sessions from fundamentals to advanced practices"
+skill = "bmad-teach-me-testing"
+
+[[agent.menu]]
+code = "TF"
+description = "Test Framework — initialize production-ready test framework architecture"
+skill = "bmad-testarch-framework"
+
+[[agent.menu]]
+code = "AT"
+description = "ATDD — generate failing acceptance tests plus an implementation checklist before development"
+skill = "bmad-testarch-atdd"
+
+[[agent.menu]]
+code = "TA"
+description = "Test Automation — generate prioritized API/E2E tests, fixtures, and DoD summary for a story or feature"
+skill = "bmad-testarch-automate"
+
+[[agent.menu]]
+code = "TD"
+description = "Test Design — risk assessment plus coverage strategy for system or epic scope"
+skill = "bmad-testarch-test-design"
+
+[[agent.menu]]
+code = "TR"
+description = "Trace Coverage — map requirements, specs, or inferred journeys to tests (Phase 1) and make quality gate decision (Phase 2)"
+skill = "bmad-testarch-trace"
+
+[[agent.menu]]
+code = "NR"
+description = "Non-Functional Requirements — assess NFRs and recommend actions"
+skill = "bmad-testarch-nfr"
+
+[[agent.menu]]
+code = "CI"
+description = "Continuous Integration — recommend and scaffold CI/CD quality pipeline"
+skill = "bmad-testarch-ci"
+
+[[agent.menu]]
+code = "RV"
+description = "Review Tests — perform a quality check against written tests using comprehensive knowledge base and best practices"
+skill = "bmad-testarch-test-review"

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

@@ -167,7 +167,8 @@ describe('User API Contract', () => {
 ```json
 {
   "scripts": {
-    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "test:pact:consumer": "./scripts/check-pact-determinism.sh 'npm run test:pact:consumer:run' 3 ./pacts",
+    "test:pact:consumer:run": "vitest run --config vitest.config.pact.ts",
     "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
   }
 }
@@ -1024,7 +1025,7 @@ Before implementing contract testing, verify:
 ## Integration Points
 
 - Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
-- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md` (consumer vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true`), `pactjs-utils-consumer-helpers.md` (PactV4 one-interaction-per-`it()` rule), `pactjs-utils-provider-verifier.md` (provider vitest `pool: 'forks'` + `singleFork: true` — same rule as consumer), `pact-broker-webhooks.md` (PactFlow → GitHub webhook auth, PAT rotation, staleness monitoring)
 - Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
 
 ---
@@ -1033,18 +1034,34 @@ Before implementing contract testing, verify:
 
 When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
 
-| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
-| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
-| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
-| 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                |
-| 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.)                            |
-| 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                          |
-
-See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                                                                    |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                                                     |
+| 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                                                     |
+| 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.)                                                                 |
+| 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).
+
+### 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 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`).
+
+Provider suites require the same `pool: 'forks'` + `singleFork: true` combination — see `pactjs-utils-provider-verifier.md` Example 7.
+
+### Webhook Auth & Staleness
+
+When `can-i-deploy` in a consumer repo times out with `There is no verified pact between <consumer> and the version of <provider> currently in <env>` — check the provider's PactFlow webhook. Silent failures from an expired/revoked GitHub PAT are the most common non-code cause of this symptom. See `pact-broker-webhooks.md` for the dedicated-machine-user pattern, classic-PAT-with-`repo`-scope rationale, rotation runbook, and staleness monitoring options.
 
 _Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_

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

@@ -0,0 +1,237 @@
+# Pact Broker Webhooks (PactFlow → GitHub)
+
+## Principle
+
+Configure PactFlow webhooks to trigger provider verification in GitHub Actions via a dedicated GitHub machine user, a long-lived classic Personal Access Token (PAT), and a PactFlow-stored secret. Monitor for silent webhook failures so an expired/revoked token does not quietly block deployments for days.
+
+## Rationale
+
+### 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.
+- 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.
+
+### Why a dedicated GitHub machine user (not a personal PAT)
+
+- Personal PATs die when the person leaves the company, rotates laptops, or revokes credentials during a security review. The contract test pipeline then breaks for reasons unrelated to any code change.
+- A dedicated machine user (e.g., `pactflow-<org>`) is owned by the org, has only the repos it needs, and the PAT lifecycle is controlled by the security/platform team.
+- GitHub **billing does not count** machine users added as outside collaborators to the specific repos they need — confirm with the org owner before assuming it's free.
+
+### Why classic PAT with `repo` scope and no expiration
+
+- PactFlow's webhook calls the GitHub REST API's `repository_dispatch` endpoint. This endpoint requires the **`repo` scope** on a classic PAT (fine-grained PATs work for many flows but have edge cases with `repository_dispatch` that are not universally supported at time of writing — verify with current GitHub docs).
+- Classic PATs support "No expiration" — required to avoid the silent-failure trap every 90 days. GitHub warns against this for human users; for a locked-down machine-user PAT stored in PactFlow's secret vault, the security trade-off is documented and accepted.
+- The alternative — rotating a PAT every 30/60/90 days — requires tooling and coordination most teams don't yet have. Long-lived + monitored + machine-user-owned is the pragmatic default.
+
+## Pattern Examples
+
+### Example 1: Webhook URL, Headers, and Body
+
+```json
+{
+  "description": "Notify <provider-repo> when a consumer contract requires verification",
+  "events": [{ "name": "contract_requiring_verification_published" }],
+  "provider": { "name": "<provider-pacticipant-name>" },
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/<org>/<provider-repo>/dispatches",
+    "headers": {
+      "Accept": "application/vnd.github+json",
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "User-Agent": "PactFlow",
+      "X-GitHub-Api-Version": "2022-11-28"
+    },
+    "body": {
+      "event_type": "contract_requiring_verification_published",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "sha": "${pactbroker.providerVersionNumber}",
+        "branch": "${pactbroker.providerVersionBranch}",
+        "consumer_name": "${pactbroker.consumerName}",
+        "consumer_version_number": "${pactbroker.consumerVersionNumber}",
+        "consumer_version_tags": "${pactbroker.consumerVersionTags}",
+        "consumer_version_branch": "${pactbroker.consumerVersionBranch}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- `${user.githubToken}` references a PactFlow **secret** stored in `Settings → Secrets` (web UI: `/settings/secrets`). The secret holds the classic PAT — never inline the token in the webhook body.
+- `${pactbroker.*}` are PactFlow-injected template variables; the provider workflow reads them from `github.event.client_payload`.
+- Use the `contract_requiring_verification_published` event (not `contract_published`) — the former fires only when a new pact _content_ change needs verification; the latter fires on every publish, including no-op republishes.
+
+### Example 2: Provider GitHub Actions Workflow (Triggered by Webhook)
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+name: contract-test-provider
+
+on:
+  repository_dispatch:
+    types: [contract_requiring_verification_published]
+  push:
+    branches: [main]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    env:
+      PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+      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 }}
+    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 }}
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - name: Run provider verification
+        run: npm run test:pact:provider
+      - name: Can I deploy provider?
+        if: github.event_name == 'push'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- `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.
+- `PACT_PAYLOAD_URL` makes `buildVerifierOptions` verify only the triggering pact (see `pactjs-utils-provider-verifier.md` Example 1).
+
+### Example 3: Secret Rotation Runbook
+
+**Trigger**: `can-i-deploy` in a consumer repo times out with `There is no verified pact between <consumer-version> and the version of <provider> currently in <env>` — AND the provider's `contract-test-provider` workflow shows no recent `repository_dispatch` runs.
+
+**Diagnosis**:
+
+1. In PactFlow UI: `Settings → Webhooks → <webhook-id> → Test`. A `401 Unauthorized` from GitHub confirms the token is dead.
+2. In PactFlow UI: the webhook's "Last executed at" is hours/days stale while consumer pacts are actively being published.
+
+**Rotation**:
+
+1. Log in to GitHub as the dedicated machine user (e.g., `pactflow-<org>`). **Do not use a personal account** — the whole point of the machine user is that the token outlives any individual.
+2. `Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)`.
+3. Configure the token:
+   - Name: `pactflow-webhook-<yyyy-mm-dd>`
+   - Expiration: **No expiration** (accepted trade-off for a locked-down machine-user token stored in PactFlow's secret vault)
+   - Scopes: **`repo`** (full repo scope is required by `repository_dispatch`; `public_repo` alone is insufficient for private repos)
+4. Copy the new token value (shown only once).
+5. In PactFlow UI: `Settings → Secrets → <secret-name>` (e.g., `githubToken`). Paste the new token into the **value** field and save. The webhook does not need to be edited — it references the secret by name via `${user.<secret-name>}`.
+6. Re-test the webhook: `Settings → Webhooks → <webhook-id> → Test`. Expect `HTTP/1.1 204 No Content` (GitHub's success response for `repository_dispatch`).
+7. In the provider repo: watch `Actions → contract-test-provider` for the newly dispatched run. Re-run the original consumer CI to confirm `can-i-deploy` now passes.
+8. Revoke the old token: in the machine user's GitHub settings, delete the previous `pactflow-webhook-*` token so a leaked copy can't be reused.
+
+**Why no expiration**: A token with a 90-day expiry rotates 4× per year. Each rotation is a silent-failure window if the runbook isn't executed proactively. With monitoring (Example 4) + a locked-down machine-user-owned PAT that is only stored in PactFlow, long-lived is safer than short-lived-but-forgotten.
+
+### Example 4: Staleness Monitoring (Detect Silent Webhook Failures)
+
+**Goal**: Alert the team if verification results haven't been published for a pacticipant pair in the last N hours, so an expired PAT or network issue doesn't silently block `can-i-deploy` for days.
+
+Pick one of these (in increasing order of investment):
+
+**Option A — Daily sanity CI job (cheapest)**:
+
+```yaml
+# .github/workflows/pact-staleness-check.yml
+name: pact-staleness-check
+on:
+  schedule:
+    - cron: '0 9 * * 1-5' # weekdays 09:00 UTC
+  workflow_dispatch:
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fail if latest verification for <pair> is older than 24h
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+        run: |
+          # Query broker matrix for newest verification timestamp for consumer/provider pair.
+          # Exit 1 if > 24h old; team gets an email on the failed scheduled run.
+          ./scripts/assert-recent-verification.sh <consumer> <provider> 86400
+```
+
+**Option B — PactFlow metrics endpoint**: Use the SmartBear MCP `get_metrics` / `get_team_metrics` tool (see `pact-mcp.md`) to surface verification freshness in a dashboard or Slack digest.
+
+**Option C — Webhook delivery log**: PactFlow logs every webhook execution. Ship those logs to your SIEM / observability stack and alert on sustained 4xx responses from `api.github.com`.
+
+**Key Points**:
+
+- The point is not "which option you pick" — it's that **you pick at least one**. Without monitoring, the first time you learn the webhook is dead is when a release is blocked.
+- Alert threshold should match your consumer-publish cadence: if consumers publish daily, alert after 24–48h of silence; if hourly, after 3–6h.
+- Keep the alert noise-free: page only on sustained staleness, not a single missed run.
+
+## Key Points
+
+- **Dedicated machine user owns the PAT** — never a personal PAT. Name it `pactflow-<org>` or similar; give it outside-collaborator access only to the specific provider repos.
+- **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.
+- **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.
+
+## Related Fragments
+
+- `pactjs-utils-provider-verifier.md` — how `PACT_PAYLOAD_URL` from the webhook's `client_payload.pact_url` is consumed by `buildVerifierOptions`
+- `pact-consumer-framework-setup.md` — consumer CI flow that issues `can-i-deploy` and silently times out when the webhook is dead
+- `pact-mcp.md` — SmartBear MCP tools (`Matrix`, `Metrics - All`) useful for staleness monitoring dashboards
+- `contract-testing.md` — foundational CDC patterns and resilience coverage
+
+## Anti-Patterns
+
+### Wrong: Using a human's personal PAT
+
+```
+# ❌ PactFlow secret githubToken stores the lead engineer's personal classic PAT
+# When they leave / rotate / revoke → all provider verifications stop silently
+```
+
+### Right: Dedicated machine user owns the PAT
+
+```
+# ✅ Machine user `pactflow-<org>` generates the PAT; secret is owned by the org
+# PAT lifecycle is decoupled from any individual's employment or laptop state
+```
+
+### Wrong: No staleness monitoring
+
+```
+# ❌ No scheduled check for verification recency
+# First signal that the webhook is dead: a blocked release PR, several days later
+```
+
+### Right: Daily scheduled sanity check
+
+```
+# ✅ Scheduled workflow fails if latest verification > 24h old
+# Team gets email alert on failed scheduled run → rotate PAT before anyone is blocked
+```
+
+### Wrong: Short-expiration PAT with no rotation tooling
+
+```
+# ❌ 90-day expiry PAT, no calendar reminder, no runbook
+# Breaks every 90 days for a day or two until someone notices
+```
+
+### Right: No-expiration PAT on machine user + monitoring + documented runbook
+
+```
+# ✅ Long-lived PAT, scoped narrowly, stored in PactFlow, monitored for staleness
+# Rotation is intentional (security review, suspected leak) not calendar-driven
+```
+
+_Source: PactFlow webhook documentation, GitHub `repository_dispatch` REST API, seon-mcp-server / seon-admin-panel production incident April 2026_