ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/resources/knowledge/webhook-waiting-querying.md

@@ -0,0 +1,167 @@
+# Webhook Waiting and Querying Patterns
+
+## Principle
+
+`waitFor` and `waitForCount` poll until matching webhooks arrive; `getReceived` queries without waiting. Always drain preceding events before asserting on subsequent ones. Scope templates by entity ID to prevent parallel worker cross-contamination.
+
+## Pattern Examples
+
+### Example 1: waitFor — single webhook
+
+Poll until the first webhook matching the template arrives. Returns the typed `ReceivedWebhook<T>`.
+
+```typescript
+const webhook = await webhookRegistry.waitFor(movieCreated(movieId));
+
+expect(webhook.body).toMatchObject({
+  event: 'movie.created',
+  timestamp: expect.any(String),
+  data: {
+    id: movieId,
+    name: movie.name,
+    year: movie.year,
+    rating: movie.rating,
+  },
+});
+```
+
+### Example 2: The drain pattern — sequential events
+
+When testing a downstream event (e.g. deletion), always `waitFor` the preceding event first. Without the drain, the create webhook may remain in the journal and interfere with cleanup or subsequent polling.
+
+```typescript
+test('movie deletion triggers a webhook with correct payload', async ({ authToken, addMovie, deleteMovie, webhookRegistry }) => {
+  const movie = generateMovieWithoutId();
+  const { body: createResponse } = await addMovie(authToken, movie);
+  const movieId = createResponse.data.id;
+
+  await log.step('Drain the create webhook before testing the delete path');
+  await webhookRegistry.waitFor(movieCreated(movieId)); // drain — consume the create event
+
+  await deleteMovie(authToken, movieId);
+
+  await log.step('Wait for the delete webhook');
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+**Why drain?** If you skip the drain and go directly to `waitFor(movieDeleted)`, the create webhook is already in the journal. The delete webhook may arrive and be cleaned up by another test before your poll reaches it. Draining makes the event order explicit and removes the ambiguity.
+
+### Example 3: waitForCount — collect N webhooks concurrently
+
+Collect exactly N matching webhooks. Use `matchPredicate` with all IDs to prevent cross-worker contamination when running `fullyParallel: true`:
+
+```typescript
+await log.step('Create two movies concurrently');
+const [{ body: res1 }, { body: res2 }] = await Promise.all([
+  addMovie(authToken, generateMovieWithoutId()),
+  addMovie(authToken, generateMovieWithoutId()),
+]);
+
+const [id1, id2] = [res1.data.id, res2.data.id];
+
+const batchTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.created.batch')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${id1} or ${id2}`, (p) => p.data.id === id1 || p.data.id === id2)
+  .withTimeout(15_000)
+  .withInterval(500)
+  .build();
+
+const webhooks = await webhookRegistry.waitForCount(batchTemplate, 2);
+
+expect(webhooks).toHaveLength(2);
+const receivedIds = webhooks.map((w) => w.body.data.id);
+expect(receivedIds).toContain(id1);
+expect(receivedIds).toContain(id2);
+expect(new Set(receivedIds).size).toBe(2); // guard against the same ID delivered twice
+```
+
+### Example 4: getReceived — query without waiting
+
+Query the journal without polling. Useful for asserting presence of webhooks after a `waitFor`, or for method/URL filtering.
+
+```typescript
+await webhookRegistry.waitFor(movieCreated(movieId)); // wait first
+
+const all = await webhookRegistry.getReceived();
+expect(all.length).toBeGreaterThanOrEqual(1);
+
+// Method filter — all sample-app webhooks are delivered via POST
+const postOnly = await webhookRegistry.getReceived({ method: 'POST' });
+expect(postOnly.every((w) => w.method === 'POST')).toBe(true);
+
+// URL pattern filter — match the webhooks endpoint path
+const byUrl = await webhookRegistry.getReceived({ urlPattern: '/webhooks' });
+expect(byUrl.every((w) => w.url.includes('/webhooks'))).toBe(true);
+```
+
+`getReceived` accepts `WebhookQueryFilter`:
+
+```typescript
+type WebhookQueryFilter = {
+  urlPattern?: string; // glob or regex string
+  method?: string; // HTTP method filter
+  since?: Date; // only return webhooks after this timestamp
+};
+```
+
+Note: `getReceived` is a direct passthrough to the provider — it does **not** automatically apply the `startedAt` filter. Only `waitFor` and `waitForCount` apply the since-filter internally during polling. If you need to scope a manual `getReceived` call to this test's time window, record your own timestamp before the action under test and pass `{ since: myTimestamp }` explicitly.
+
+## Parallel Worker Safety
+
+Always scope template factories to the entity's ID:
+
+```typescript
+// ✅ Scoped — only matches webhooks for this specific movie
+const movieCreated = (movieId: number) =>
+  webhookTemplate('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId) // scoped by ID
+    .build();
+
+// ❌ Unscoped — will match any movie.created from any parallel worker
+const movieCreatedUnscoped = webhookTemplate('movie.created').matchField('event', 'movie.created').build();
+```
+
+## Method Summary
+
+| Method                      | Returns                         | Description                                                                                       |
+| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `waitFor(template)`         | `Promise<ReceivedWebhook<T>>`   | Poll until first match; throws `WebhookTimeoutError` on timeout                                   |
+| `waitForCount(template, n)` | `Promise<ReceivedWebhook<T>[]>` | Poll until N matches; throws `WebhookTimeoutError` on timeout                                     |
+| `getReceived(filter?)`      | `Promise<ReceivedWebhook[]>`    | Direct passthrough to provider — no automatic since-filter; pass `{ since }` explicitly if needed |
+| `resetJournal()`            | `Promise<void>`                 | Wipe the entire journal and clear matchedIds                                                      |
+| `cleanup()`                 | `Promise<void>`                 | Delete matched webhooks (`matched-only`) or reset journal (`full-reset`)                          |
+
+## Anti-Patterns
+
+**DON'T skip the drain for sequential events:**
+
+```typescript
+// Bad: direct jump to delete webhook — create webhook pollutes the journal
+await addMovie(authToken, movie);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+**DO drain preceding events:**
+
+```typescript
+// Good: drain create first, then wait for delete
+await webhookRegistry.waitFor(movieCreated(movieId)); // drain
+await deleteMovie(authToken, movieId);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — How to build templates
+- `webhook-timeout-error.md` — What to do when waitFor times out
+- `recurse.md` — The polling primitive used internally by the registry

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/resources/tea-index.csv

@@ -7,7 +7,7 @@ playwright-config,Playwright Config Guardrails,"Environment switching, timeout s
 ci-burn-in,CI and Burn-In Strategy,"Staged jobs, shard orchestration, burn-in loops, artifact policy","ci,automation,flakiness",extended,knowledge/ci-burn-in.md
 selective-testing,Selective Test Execution,"Tag/grep usage, spec filters, diff-based runs, promotion rules","risk-based,selection,strategy",extended,knowledge/selective-testing.md
 feature-flags,Feature Flag Governance,"Enum management, targeting helpers, cleanup, release checklists","feature-flags,governance,launchdarkly",specialized,knowledge/feature-flags.md
-contract-testing,Contract Testing Essentials,"Pact publishing, provider verification, resilience coverage","contract-testing,pact,api,backend,microservices,service-contract",specialized,knowledge/contract-testing.md
+contract-testing,Contract Testing Essentials,"Pact publishing, provider verification, resilience coverage, PactV4 four-rule determinism & FFI safety block (fileParallelism + pool:forks + singleFork + determinism gate)","contract-testing,pact,api,backend,microservices,service-contract,vitest,ffi,determinism,pactv4",specialized,knowledge/contract-testing.md
 email-auth,Email Authentication Testing,"Magic link extraction, state preservation, caching, negative flows","email-authentication,security,workflow",specialized,knowledge/email-auth.md
 error-handling,Error Handling Checks,"Scoped exception handling, retry validation, telemetry logging","resilience,error-handling,stability,api,backend",extended,knowledge/error-handling.md
 visual-debugging,Visual Debugging Toolkit,"Trace viewer usage, artifact expectations, accessibility integration","debugging,dx,tooling,ui",specialized,knowledge/visual-debugging.md
@@ -33,11 +33,19 @@ network-error-monitor,Network Error Monitor,"HTTP 4xx/5xx detection for UI tests
 fixtures-composition,Fixtures Composition,"mergeTests composition patterns for combining utilities","fixtures,playwright-utils",extended,knowledge/fixtures-composition.md
 api-testing-patterns,API Testing Patterns,"Pure API test patterns without browser: service testing, microservices, GraphQL","api,backend,service-testing,api-testing,microservices,graphql,no-browser",specialized,knowledge/api-testing-patterns.md
 pactjs-utils-overview,Pact.js Utils Overview,"Installation, contract testing flows, utility table (createProviderState, toJsonMap, setJsonContent, setJsonBody)","pactjs-utils,contract-testing,pact,api,backend,microservices",specialized,knowledge/pactjs-utils-overview.md
-pactjs-utils-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
-pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody; PactV4 one-interaction-per-it() determinism rule","pactjs-utils,consumer,contract-testing,pact,api,determinism,pactv4",specialized,knowledge/pactjs-utils-consumer-helpers.md
+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, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",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), 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-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
 pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/steps-c/step-01-preflight.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-01-preflight'
 description: 'Verify prerequisites and gather project context'
-nextStepFile: './step-02-select-framework.md'
+nextStepFile: '{skill-root}/steps-c/step-02-select-framework.md'
 outputFile: '{test_artifacts}/framework-setup-progress.md'
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/steps-c/step-02-select-framework.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-02-select-framework'
 description: 'Select Playwright or Cypress and justify choice'
-nextStepFile: './step-03-scaffold-framework.md'
+nextStepFile: '{skill-root}/steps-c/step-03-scaffold-framework.md'
 outputFile: '{test_artifacts}/framework-setup-progress.md'
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/steps-c/step-03-scaffold-framework.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-03-scaffold-framework'
 description: 'Create framework scaffold with adaptive orchestration (agent-team, subagent, or sequential)'
-nextStepFile: './step-04-docs-and-scripts.md'
+nextStepFile: '{skill-root}/steps-c/step-04-docs-and-scripts.md'
 knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/framework-setup-progress.md'
 ---
@@ -212,9 +212,11 @@ Read `{config_source}` and use `{knowledgeIndex}` to load fragments based on `co
 
 **If Pact.js Utils enabled** (`config.tea_use_pactjs_utils`):
 
-- `pact-consumer-framework-setup.md` (CRITICAL: load this for directory structure, scripts, CI workflow, and PactV4 patterns)
-- `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md`, `contract-testing.md`
+- `pact-consumer-framework-setup.md` (CRITICAL: load this for directory structure, scripts, CI workflow, and PactV4 patterns — includes `fileParallelism: false` + `pool: 'forks'` + `singleFork: true`, determinism gate, and `jq` publish normalization)
+- `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md` (one-interaction-per-`it()` rule), `pactjs-utils-provider-verifier.md` (same `pool: 'forks'` + `singleFork` rule applies to consumer AND provider), `pactjs-utils-request-filter.md`, `contract-testing.md`
+- `pact-broker-webhooks.md` — when scaffolding the provider repo and any CI step that depends on `can-i-deploy`
 - Recommend installing `@seontechnologies/pactjs-utils` and `@pact-foundation/pact`
+- Ensure `jq` is available on CI runners (default on `ubuntu-latest`; document `brew install jq` for macOS dev machines) — required by `scripts/check-pact-determinism.sh` and `scripts/publish-pact.sh`
 
 **If Pact.js Utils disabled but contract testing relevant:**
 
@@ -264,12 +266,14 @@ Create helpers for:
 
 Create Node.js/TypeScript contract test samples per `pact-consumer-framework-setup.md`:
 
-- **Consumer test**: Example using PactV4 `addInteraction()` builder + `createProviderState` + real consumer code with URL injection (`.pacttest.ts` extension)
+- **Consumer test**: Example using PactV4 `addInteraction()` builder + `createProviderState` + real consumer code with URL injection (`.pacttest.ts` extension). **One `addInteraction()` per `it()` block** — never chain multiple interactions in a single test (PactV4 FFI drops them non-deterministically; see `pactjs-utils-consumer-helpers.md` Example 6).
 - **Support files**: Pact config factory (`pact-config.ts`), provider state factories (`provider-states.ts`), local consumer-helpers shim (`consumer-helpers.ts`)
-- **Vitest config**: Minimal `vitest.config.pact.ts` (do NOT copy settings from unit config)
-- **Shell scripts**: `env-setup.sh`, `publish-pact.sh`, `can-i-deploy.sh`, `record-deployment.sh` in `scripts/`
+- **Vitest config (consumer)**: Minimal `vitest.config.pact.ts` with **`fileParallelism: false` AND `pool: 'forks'` + `poolOptions.forks.singleFork: true`** (both required — `fileParallelism: false` prevents shared pact JSON corruption from parallel workers; forks pool + singleFork prevents the Pact Rust FFI from leaking state across files and flaking on Linux CI. See `pact-consumer-framework-setup.md` Example 2). Do NOT copy settings from unit config.
+- **Vitest config (provider)**: `vitest.config.contract.ts` with **`pool: 'forks'` + `poolOptions.forks.singleFork: true`** (same rule as consumer; required for message providers and multi-file HTTP providers; see `pactjs-utils-provider-verifier.md` Example 7).
+- **Shell scripts**: `env-setup.sh`, `check-pact-determinism.sh` (primary defense against non-deterministic pact generation), `publish-pact.sh` (with `jq -S` interaction sort normalization), `can-i-deploy.sh`, `record-deployment.sh` in `scripts/`
+- **package.json scripts**: Split `test:pact:consumer` (determinism gate — runs `check-pact-determinism.sh` with 3 runs) and `test:pact:consumer:run` (inner single-pass vitest invocation). CI and local both call `npm run test:pact:consumer` for 1:1 parity.
 - **CI workflow**: `contract-test-consumer.yml` with detect-breaking-change action
-- **package.json scripts**: `test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`
+- **package.json scripts**: `test:pact:consumer` (determinism gate), `test:pact:consumer:run` (inner single-pass vitest), `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`
 - **.gitignore**: Add `/pacts/` and `pact-logs/`
 
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/steps-c/step-04-docs-and-scripts.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-04-docs-and-scripts'
 description: 'Document setup and add package.json scripts'
-nextStepFile: './step-05-validate-and-summary.md'
+nextStepFile: '{skill-root}/steps-c/step-05-validate-and-summary.md'
 outputFile: '{test_dir}/README.md'
 progressFile: '{test_artifacts}/framework-setup-progress.md'
 ---

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-framework/steps-c/step-05-validate-and-summary.md

@@ -91,3 +91,11 @@ Report:
 
 - 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-framework/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-framework/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-framework/steps-v/step-01-validate.md

@@ -2,7 +2,7 @@
 name: 'step-01-validate'
 description: 'Validate workflow outputs against checklist'
 outputFile: '{test_artifacts}/framework-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-nfr/SKILL.md

@@ -3,4 +3,83 @@ name: bmad-testarch-nfr
 description: 'Assess NFRs like performance security and reliability. Use when the user says "lets assess NFRs" or "I want to evaluate non-functional requirements"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+# Non-Functional Requirements Assessment
+
+**Goal:** Assess non-functional requirements (performance, security, reliability, maintainability) before release with evidence-based 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-nfr/customize.toml

@@ -0,0 +1,40 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for bmad-testarch-nfr. 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-nfr/instructions.md

@@ -33,11 +33,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-nfr/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_