ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-c/step-02-load-context.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-02-load-context'
 description: 'Load documents, configuration, and knowledge fragments for the chosen mode'
-nextStepFile: './step-03-risk-and-testability.md'
+nextStepFile: '{skill-root}/steps-c/step-03-risk-and-testability.md'
 knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/test-design-progress.md'
 ---
@@ -212,8 +212,11 @@ Summarize what was loaded and confirm with the user if anything is missing.
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-02-load-context']
   lastStep: 'step-02-load-context'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -221,8 +224,11 @@ Summarize what was loaded and confirm with the user if anything is missing.
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-02-load-context'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-02-load-context'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-c/step-03-risk-and-testability.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-03-risk-and-testability'
 description: 'Perform testability review (system-level) and risk assessment'
-nextStepFile: './step-04-coverage-plan.md'
+nextStepFile: '{skill-root}/steps-c/step-04-coverage-plan.md'
 outputFile: '{test_artifacts}/test-design-progress.md'
 ---
 
@@ -82,8 +82,11 @@ Summarize the highest risks and their mitigation priorities.
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-03-risk-and-testability']
   lastStep: 'step-03-risk-and-testability'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -91,8 +94,11 @@ Summarize the highest risks and their mitigation priorities.
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-03-risk-and-testability'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-03-risk-and-testability'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-c/step-04-coverage-plan.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-04-coverage-plan'
 description: 'Design test coverage, priorities, execution strategy, and estimates'
-nextStepFile: './step-05-generate-output.md'
+nextStepFile: '{skill-root}/steps-c/step-05-generate-output.md'
 outputFile: '{test_artifacts}/test-design-progress.md'
 ---
 
@@ -95,8 +95,11 @@ Define thresholds:
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-04-coverage-plan']
   lastStep: 'step-04-coverage-plan'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -104,8 +107,11 @@ Define thresholds:
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-04-coverage-plan'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-04-coverage-plan'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-c/step-05-generate-output.md

@@ -196,8 +196,11 @@ Summarize:
 
   ```yaml
   ---
+  workflowStatus: 'completed'
+  totalSteps: 5
   stepsCompleted: ['step-05-generate-output']
   lastStep: 'step-05-generate-output'
+  nextStep: ''
   lastSaved: '{date}'
   ---
   ```
@@ -205,8 +208,11 @@ Summarize:
   Then write this step's output below the frontmatter.
 
 - **If `{progressFile}` already exists**, update:
+  - Set `workflowStatus: 'completed'`
+  - Set `totalSteps: 5`
   - Add `'step-05-generate-output'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-05-generate-output'`
+  - Set `nextStep: ''`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
@@ -220,3 +226,11 @@ Summarize:
 
 - Skipped sequence steps or missing outputs
   **Master Rule:** Skipping steps is FORBIDDEN.
+
+## On Complete
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolver succeeds and returns a non-empty `workflow.on_complete`, execute that value as the final terminal instruction before exiting.
+
+If the resolver fails, returns no output, or resolves an empty value, skip the hook and exit normally.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-e/step-01-assess.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-01-assess'
 description: 'Load an existing output for editing'
-nextStepFile: './step-02-apply-edit.md'
+nextStepFile: '{skill-root}/steps-e/step-02-apply-edit.md'
 ---
 
 # Step 1: Assess Edit Target

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-e/step-02-apply-edit.md

@@ -58,3 +58,11 @@ Summarize the edits applied.
 ### ❌ SYSTEM FAILURE:
 
 - Unconfirmed edits or missing update
+
+## On Complete
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolver succeeds and returns a non-empty `workflow.on_complete`, execute that value as the final terminal instruction before exiting.
+
+If the resolver fails, returns no output, or resolves an empty value, skip the hook and exit normally.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/steps-v/step-01-validate.md

@@ -2,7 +2,7 @@
 name: 'step-01-validate'
 description: 'Validate workflow outputs against checklist'
 outputFile: '{test_artifacts}/test-design-validation-report.md'
-validationChecklist: '../checklist.md'
+validationChecklist: '{skill-root}/checklist.md'
 ---
 
 # Step 1: Validate Outputs
@@ -65,3 +65,11 @@ Write a validation report to `{outputFile}` with PASS/WARN/FAIL per section.
 
 - Skipped checklist items
 - No report produced
+
+## On Complete
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow.on_complete`
+
+If the resolver succeeds and returns a non-empty `workflow.on_complete`, execute that value as the final terminal instruction before exiting.
+
+If the resolver fails, returns no output, or resolves an empty value, skip the hook and exit normally.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/test-design-architecture-template.md

@@ -1,6 +1,9 @@
 ---
+workflowStatus: ''
+totalSteps: 5
 stepsCompleted: []
 lastStep: ''
+nextStep: ''
 lastSaved: ''
 workflowType: 'testarch-test-design'
 inputDocuments: []

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/test-design-qa-template.md

@@ -1,6 +1,9 @@
 ---
+workflowStatus: ''
+totalSteps: 5
 stepsCompleted: []
 lastStep: ''
+nextStep: ''
 lastSaved: ''
 workflowType: 'testarch-test-design'
 inputDocuments: []

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-design/test-design-template.md

@@ -1,6 +1,9 @@
 ---
+workflowStatus: ''
+totalSteps: 5
 stepsCompleted: []
 lastStep: ''
+nextStep: ''
 lastSaved: ''
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/SKILL.md

@@ -3,4 +3,83 @@ name: bmad-testarch-test-review
 description: 'Review test quality using best practices validation. Use when user says "lets review tests" or "I want to evaluate test quality"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+# Test Quality Review
+
+**Goal:** Review test quality using a comprehensive knowledge base and best-practices validation.
+
+**Role:** You are the Master Test Architect.
+
+You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
+
+## Conventions
+
+- Bare paths (e.g. `instructions.md`) 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.
+- Resolve sibling workflow files such as `instructions.md`, `checklist.md`, `steps-c/...`, `steps-e/...`, `steps-v/...`, and templates from `{skill-root}`.
+
+## On Activation
+
+### Step 1: Resolve the Workflow Block
+
+Run: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`
+
+**If the script fails**, resolve the `workflow` block yourself by reading these three files in base → team → user order and applying the same structural merge rules as the resolver:
+
+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
+
+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.
+
+### Step 2: Execute Prepend Steps
+
+Execute each entry in `{workflow.activation_steps_prepend}` in order before proceeding.
+
+### Step 3: Load Persistent Facts
+
+Treat every entry in `{workflow.persistent_facts}` as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs resolved from `{project-root}` — expand them and load every matching file in lexical path order as facts. All other entries are facts verbatim.
+
+### Step 4: Load Config
+
+Load config from `{project-root}/_bmad/tea/config.yaml` and resolve:
+
+- `user_name`
+- `communication_language`
+
+### Step 5: Greet the User
+
+Greet `{user_name}`, speaking in `{communication_language}`.
+
+### Step 6: Execute Append Steps
+
+Execute each entry in `{workflow.activation_steps_append}` in order.
+
+Activation is complete. Begin the workflow below.
+
+## Workflow Architecture
+
+This workflow uses **tri-modal step-file architecture**:
+
+- **Create mode (steps-c/)**: primary execution flow for new runs and resume continuation
+- **Validate mode (steps-v/)**: validation against checklist
+- **Edit mode (steps-e/)**: revise existing outputs
+
+## Initialization Sequence
+
+### 1. Mode Determination
+
+"Welcome to the workflow. What would you like to do?"
+
+- **[C] Create** — Run the workflow from the beginning
+- **[R] Resume** — Resume an interrupted Create workflow
+- **[V] Validate** — Validate existing outputs
+- **[E] Edit** — Edit existing outputs
+
+### 2. Route to First Step
+
+- **If C:** Load `{skill-root}/steps-c/step-01-load-context.md`
+- **If R:** Load `{skill-root}/steps-c/step-01b-resume.md` (Create-mode continuation)
+- **If V:** Load `{skill-root}/steps-v/step-01-validate.md`
+- **If E:** Load `{skill-root}/steps-e/step-01-assess.md`

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/customize.toml

@@ -0,0 +1,40 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-testarch-test-review. Mirrors the
+# agent customization shape under the [workflow] namespace.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+
+# Steps to run before the standard activation (config load, greet).
+# Overrides append. Use for pre-flight loads, compliance checks, etc.
+
+activation_steps_prepend = []
+
+# Steps to run after greet but before the workflow begins.
+# Overrides append. Use for context-heavy setup that should happen
+# once the user has been acknowledged.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (testing standards, framework conventions, compliance constraints).
+# Distinct from the runtime memory sidecar — these are static context
+# loaded on activation. Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "Every test must run deterministically in CI."
+#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/test-standards.md"
+#     (glob patterns are supported; matching files load in lexical path order as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# Scalar: executed when the workflow reaches its terminal step in any
+# mode (create, validate, edit), after the final outputs are produced.
+# Override wins. Leave empty for no custom post-completion behavior.
+
+on_complete = ""

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/instructions.md

@@ -35,11 +35,11 @@ From `workflow.yaml`, resolve:
 ### 2. First Step
 
 Load, read completely, and execute:
-`./steps-c/step-01-load-context.md`
+`{skill-root}/steps-c/step-01-load-context.md`
 
 ### 3. Resume Support
 
 If the user selects **Resume** mode, load, read completely, and execute:
-`./steps-c/step-01b-resume.md`
+`{skill-root}/steps-c/step-01b-resume.md`
 
 This checks the output document for progress tracking frontmatter and routes to the next incomplete step.

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/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
 
 ---
@@ -1047,4 +1048,19 @@ When `tea_use_pactjs_utils` is enabled, the following utilities replace manual b
 
 See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
 
+### 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/workflows/testarch/bmad-testarch-test-review/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_