ma-agents 3.6.2 → 3.9.0

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/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-test-review/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-test-review/steps-c/step-01-load-context.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-01-load-context'
 description: 'Load knowledge base, determine scope, and gather context'
-nextStepFile: './step-02-discover-tests.md'
+nextStepFile: '{skill-root}/steps-c/step-02-discover-tests.md'
 knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/test-review.md'
 ---
@@ -83,7 +83,7 @@ Load fragments based on their `tier` classification in `tea-index.csv`:
 
 **If `tea_use_pactjs_utils` is enabled** (and contract tests detected in review scope):
 
-Load: `pactjs-utils-overview.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md` (the 3 most relevant for reviewing provider verification tests)
+Load: `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md` (one-interaction-per-`it()` determinism rule), `pactjs-utils-provider-verifier.md` (vitest `pool: 'forks'` + `singleFork` — applies to BOTH consumer and provider), `pactjs-utils-request-filter.md`, `pact-consumer-framework-setup.md` (consumer Vitest `fileParallelism: false` + `pool: 'forks'` + `singleFork: true`, determinism gate, `jq` publish normalization), `pact-broker-webhooks.md` (webhook auth, PAT rotation, staleness monitoring — relevant if CI failure patterns include `can-i-deploy` timeouts with no verification).
 
 **If `tea_use_pactjs_utils` is disabled** but contract tests are in review scope:
 
@@ -133,7 +133,7 @@ Read `{config_source}` and check `tea_use_playwright_utils`, `tea_use_pactjs_uti
 
 **Pact.js Utils (if enabled and contract tests in review scope):**
 
-- `pactjs-utils-overview.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md`
+- `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, `pactjs-utils-request-filter.md`, `pact-consumer-di.md`, `pact-consumer-framework-setup.md`, `pact-broker-webhooks.md`
 
 **Contract Testing (if pactjs-utils disabled but contract tests in review scope):**
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/steps-c/step-02-discover-tests.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-02-discover-tests'
 description: 'Find and parse test files'
-nextStepFile: './step-03-quality-evaluation.md'
+nextStepFile: '{skill-root}/steps-c/step-03-quality-evaluation.md'
 outputFile: '{test_artifacts}/test-review.md'
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/steps-c/step-03-quality-evaluation.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-03-quality-evaluation'
 description: 'Orchestrate adaptive quality dimension checks (agent-team, subagent, or sequential)'
-nextStepFile: './step-03f-aggregate-scores.md'
+nextStepFile: '{skill-root}/steps-c/step-03f-aggregate-scores.md'
 ---
 
 # Step 3: Orchestrate Adaptive Quality Evaluation

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/steps-c/step-03a-subagent-determinism.md

@@ -46,6 +46,12 @@ This is an **isolated subagent** running in parallel with other quality dimensio
 - External API calls without mocking
 - File system operations on random paths
 - Database queries with non-deterministic ordering
+- **PactV4 consumer tests: multiple `pact.addInteraction()` in a single `it()` block** — the Rust FFI non-deterministically drops interactions (see `pactjs-utils-consumer-helpers.md` Example 6). Flag any `.pacttest.ts` file where a single `it()`/`test()` contains more than one `addInteraction()` chain.
+- **PactV4 consumer Vitest config missing `fileParallelism: false`** in `vitest.config.pact.ts` — parallel workers race on the shared pact JSON file (see `pact-consumer-framework-setup.md` Example 2). HIGH regardless of file count.
+- **PactV4 consumer Vitest config missing `pool: 'forks'` + `poolOptions.forks.singleFork: true`** in `vitest.config.pact.ts` — best current understanding is that the `@pact-foundation/pact` napi-rs binding is not robust across Vitest worker threads sharing a process; once a consumer+provider pair has ≥2 `.pacttest.ts` files, default threads pool produces reproducible "request was expected but not received" flakes on Linux CI. **Severity: HIGH if the repo has ≥2 `.pacttest.ts` files for the same consumer+provider pair; LOW (future-proof advisory) for single-file suites.** See `pact-consumer-framework-setup.md` Example 2.
+- **Pact provider Vitest config missing `pool: 'forks'` + `poolOptions.forks.singleFork: true`** in `vitest.config.contract.ts` for multi-file provider suites (especially message providers) — same pool rule as the consumer side (see `pactjs-utils-provider-verifier.md` Example 7).
+- **Consumer or provider Vitest config sets any of: `sequence.concurrent: true`, `maxConcurrency > 1`, `maxWorkers > 1`, `isolate: false`** in `vitest.config.pact.ts` / `vitest.config.contract.ts` — each defeats the serialization the forks-singleFork rule relies on. HIGH.
+- **Consumer repo lacks a determinism gate** — if `tea_use_pactjs_utils` is enabled, flag any `package.json` whose `test:pact:consumer` script does not run `scripts/check-pact-determinism.sh` (see `pact-consumer-framework-setup.md` Example 10).
 
 **MEDIUM SEVERITY Violations**:
 
@@ -105,6 +111,43 @@ if (testFileContent.includes('waitForTimeout')) {
 // ... check other patterns
 ```
 
+**Detecting Pact Vitest config violations (`vitest.config.pact.ts` / `vitest.config.contract.ts`)**
+
+Vitest configs vary widely — `defineConfig({ test: { ... } })`, `mergeConfig(base, overrides)`, `satisfies UserConfig`, imported constants, TS spreads. A full AST parse is out of scope; use this fallback heuristic and accept false-negatives only for the `mergeConfig` case, which the subagent must flag separately:
+
+```javascript
+// Resolve the config file(s). For consumer: scripts.test:pact:consumer:run in package.json
+// usually points at `vitest run --config <path>`. For provider: `vitest run --config <path>`.
+// If neither script exists but `.pacttest.ts` files exist, default to 'vitest.config.pact.ts'.
+const configPath = resolveVitestConfigPath({ scriptName: 'test:pact:consumer:run', fallback: 'vitest.config.pact.ts' });
+const src = fs.readFileSync(configPath, 'utf8');
+
+// 1. Literal-match the two mandatory lines. Tolerate single or double quotes and whitespace.
+const hasFileParallelismFalse = /\bfileParallelism\s*:\s*false\b/.test(src);
+const hasPoolForks = /\bpool\s*:\s*['"]forks['"]/.test(src);
+const hasSingleForkTrue = /\bsingleFork\s*:\s*true\b/.test(src);
+
+// 2. Flag settings that would defeat the rule if a human added them.
+const hasSequenceConcurrent = /\bsequence\s*:\s*\{[^}]*\bconcurrent\s*:\s*true/.test(src);
+const hasHighMaxConcurrency = /\bmaxConcurrency\s*:\s*([2-9]|\d{2,})/.test(src);
+const hasHighMaxWorkers = /\bmaxWorkers\s*:\s*([2-9]|\d{2,})/.test(src);
+const hasIsolateFalse = /\bisolate\s*:\s*false\b/.test(src);
+
+// 3. mergeConfig / extends fallback — we cannot reliably follow imports. Emit LOW advisory.
+const usesMergeConfig = /\bmergeConfig\s*\(/.test(src) || /\bextends\s*:/.test(src);
+
+// 4. File-count gating for the pool-forks rule.
+const pactTestCount = glob.sync('tests/contract/**/*.pacttest.ts').length;
+```
+
+**Violation emission rules** (apply in order; exit on first match per check):
+
+- Missing `fileParallelism: false` → HIGH (always)
+- Missing `pool: 'forks'` OR missing `singleFork: true`, AND `pactTestCount >= 2` → HIGH
+- Missing `pool: 'forks'` OR missing `singleFork: true`, AND `pactTestCount < 2` → LOW (future-proof advisory)
+- Any of `sequence.concurrent: true`, `maxConcurrency > 1`, `maxWorkers > 1`, `isolate: false` present → HIGH
+- `usesMergeConfig` AND any of the three mandatory matches missing → LOW + `category: "pact-config-unverifiable"` with a suggestion to inline the pool settings at the leaf config or provide a `// tea:pact-ffi-safe` marker comment the subagent can trust
+
 ### 3. Calculate Determinism Score
 
 **Scoring Logic**:

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/steps-c/step-03f-aggregate-scores.md

@@ -1,7 +1,7 @@
 ---
 name: 'step-03f-aggregate-scores'
 description: 'Aggregate quality dimension scores into overall 0-100 score'
-nextStepFile: './step-04-generate-report.md'
+nextStepFile: '{skill-root}/steps-c/step-04-generate-report.md'
 outputFile: '{test_artifacts}/test-review.md'
 ---
 

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-test-review/steps-c/step-04-generate-report.md

@@ -109,3 +109,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-test-review/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-review/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-review/steps-v/step-01-validate.md

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

@@ -3,4 +3,85 @@ name: bmad-testarch-trace
 description: 'Generate traceability matrix and quality gate decision. Use when the user says "lets create traceability matrix" or "I want to analyze test coverage"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+# Coverage Traceability & Quality Gate
+
+**Goal:** Generate a requirements-or-journeys-to-tests traceability matrix, analyze coverage, and make a quality gate decision (PASS / CONCERNS / FAIL / WAIVED).
+
+**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`
+
+Create mode resolves the coverage oracle automatically in this order: formal requirements, contract/spec artifacts, resolvable external pointers (when `allow_external_pointer_resolution` is enabled), then synthetic journeys/requirements inferred from source (when `allow_synthetic_oracle` is enabled and no formal oracle exists).

package/lib/bmad-cache/tea/src/workflows/testarch/bmad-testarch-trace/checklist.md

@@ -6,7 +6,7 @@
 This checklist covers **two sequential phases**:
 
 - **PHASE 1**: Requirements Traceability (always executed)
-- **PHASE 2**: Quality Gate Decision (executed if `enable_gate_decision: true`)
+- **PHASE 2**: Quality Gate Decision (decision fields emitted only when `allow_gate: true` and the collection is gate-eligible)
 
 ---
 
@@ -14,7 +14,7 @@ This checklist covers **two sequential phases**:
 
 ## Prerequisites Validation
 
-- [ ] Acceptance criteria are available (from story file OR inline)
+- [ ] A coverage oracle is available or inferred (formal requirements, spec, resolvable external pointer, or synthetic journeys)
 - [ ] Test suite exists (or gaps are acknowledged and documented)
 - [ ] If tests are missing, recommend `*atdd` (trace does not run it automatically)
 - [ ] Test directory path is correct (`test_dir` variable)
@@ -26,7 +26,7 @@ This checklist covers **two sequential phases**:
 ## Context Loading
 
 - [ ] Story file read successfully (if applicable)
-- [ ] Acceptance criteria extracted correctly
+- [ ] Oracle items extracted or inferred correctly
 - [ ] Story ID identified (e.g., 1.3)
 - [ ] `test-design.md` loaded (if available)
 - [ ] `tech-spec.md` loaded (if available)
@@ -51,7 +51,7 @@ This checklist covers **two sequential phases**:
 
 ## Criteria-to-Test Mapping
 
-- [ ] Each acceptance criterion mapped to tests (or marked as NONE)
+- [ ] Each oracle item mapped to tests (or marked as NONE)
 - [ ] Explicit references found (test IDs, describe blocks mentioning criterion)
 - [ ] Test level documented (E2E, API, Component, Unit)
 - [ ] Given-When-Then narrative verified for alignment
@@ -96,9 +96,11 @@ This checklist covers **two sequential phases**:
   - [ ] Criteria with UNIT-ONLY status
   - [ ] Criteria with INTEGRATION-ONLY status
 - [ ] Coverage heuristics gaps identified:
-  - [ ] Endpoints referenced in requirements but not covered by API tests
+  - [ ] Endpoints referenced in requirements/specs but not covered by API tests
   - [ ] Auth/authz criteria missing denied/invalid path tests
   - [ ] Criteria with happy-path-only coverage (missing error scenarios)
+  - [ ] Inferred UI journeys missing E2E/component coverage
+  - [ ] Inferred UI journeys missing loading/empty/error/permission state coverage
 - [ ] Gaps prioritized by risk level using test-priorities framework:
   - [ ] **CRITICAL** - P0 criteria without FULL coverage (BLOCKER)
   - [ ] **HIGH** - P1 criteria without FULL coverage (PR blocker)
@@ -164,10 +166,30 @@ Knowledge fragments referenced:
 - [ ] Quality assessment section included
 - [ ] Recommendations section included
 
-### Coverage Badge/Metric (if enabled)
-
-- [ ] Badge markdown generated
-- [ ] Metrics exported to JSON for CI/CD integration
+### Machine-Readable JSON Output
+
+- [ ] `e2e-trace-summary.json` written to `{e2e_trace_summary_output}`
+- [ ] JSON is valid and parseable
+- [ ] `schema_version` field present
+- [ ] `repo`, `collection_mode`, `collection_status`, `inventory_basis`, and `source_sha` fields populated
+- [ ] `gate_basis` populated (`priority_thresholds` when gate-eligible, `none` otherwise)
+- [ ] `snapshot_at` replaces the old `generated_at` timestamp field
+- [ ] Oracle metadata populated (`resolution_mode`, `confidence`, `sources`, `external_pointer_status`, `synthetic`)
+- [ ] `target.type` and `target.id` identify the evaluated story / epic / release / hotfix
+- [ ] `gate_status` populated only when `allow_gate: true` and `collection_status` is `COLLECTED`
+- [ ] `coverage.inventory` includes `covered`, `total`, and `pct`
+- [ ] `coverage.priority_breakdown` includes P0–P3 and `coverage.by_level` includes e2e/api/component/unit/other
+- [ ] `tests` counts are deduplicated from unique discovered tests (no per-requirement double counting)
+- [ ] `risk_summary` counts match Phase 1 gap analysis
+- [ ] `heuristics` fields populated (`endpoint_gaps`, `auth_negative_path_status`, `error_path_status`)
+- [ ] UI heuristic fields populated when using a source-derived oracle (`ui_journey_status`, `ui_state_status`)
+- [ ] `gate_criteria` thresholds and actuals match gate decision
+- [ ] `blockers` array present (may be empty)
+- [ ] `recommendations` array present (may be empty)
+- [ ] `links.trace_report_path` points to `traceability-matrix.md`
+- [ ] `links.trace_report_url`, `links.artifact_url`, and `links.journey_evidence_url` fields present (may be empty)
+- [ ] `gate-decision.json` written to `{gate_decision_output}` when gate-eligible
+- [ ] `gate-decision.json` contains `evaluated_at`, `gate_basis`, `gate_status`, `rationale`, and per-criterion status fields
 
 ### Updated Story File (if enabled)
 
@@ -181,7 +203,7 @@ Knowledge fragments referenced:
 
 ### Accuracy Checks
 
-- [ ] All acceptance criteria accounted for (none skipped)
+- [ ] All oracle items accounted for (none skipped)
 - [ ] Test IDs correctly formatted (e.g., 1.3-E2E-001)
 - [ ] File paths are correct and accessible
 - [ ] Coverage percentages calculated correctly
@@ -218,7 +240,7 @@ Knowledge fragments referenced:
 
 # PHASE 2: QUALITY GATE DECISION
 
-**Note**: Phase 2 executes only if `enable_gate_decision: true` in workflow.yaml
+**Note**: Phase 2 always emits `e2e-trace-summary.json`; gate decision fields are populated only when `allow_gate: true` and `collection_status` resolves to `COLLECTED`.
 
 ---
 
@@ -301,7 +323,7 @@ Knowledge fragments referenced:
 **P0 Criteria Evaluation:**
 
 - [ ] P0 test pass rate evaluated (must be 100%)
-- [ ] P0 acceptance criteria coverage evaluated (must be 100%)
+- [ ] P0 oracle-item coverage evaluated (must be 100%)
 - [ ] Security issues count evaluated (must be 0)
 - [ ] Critical NFR failures evaluated (must be 0)
 - [ ] Flaky tests evaluated (must be 0 if burn-in enabled)
@@ -310,9 +332,9 @@ Knowledge fragments referenced:
 **P1 Criteria Evaluation:**
 
 - [ ] P1 test pass rate evaluated (threshold: min_p1_pass_rate)
-- [ ] P1 acceptance criteria coverage evaluated (PASS >=90%, CONCERNS 80-89%, FAIL <80%)
+- [ ] P1 oracle-item coverage evaluated (PASS >=90%, CONCERNS 80-89%, FAIL <80%)
 - [ ] Overall test pass rate evaluated (threshold: min_overall_pass_rate)
-- [ ] Overall requirements coverage evaluated (threshold: >=80%)
+- [ ] Overall oracle coverage evaluated (threshold: >=80%)
 - [ ] Code coverage considered if available (informational unless explicitly required by policy)
 - [ ] P1 decision recorded: PASS or CONCERNS
 
@@ -396,8 +418,9 @@ Knowledge fragments referenced:
 
 **Outputs Saved:**
 
-- [ ] Gate decision document saved to `{output_file}`
-- [ ] Gate YAML saved to `{test_artifacts}/gate-decision-{target}.yaml`
+- [ ] Gate decision document saved to `{outputFile}`
+- [ ] `e2e-trace-summary.json` saved to `{e2e_trace_summary_output}` (always)
+- [ ] `gate-decision.json` saved to `{gate_decision_output}` (when gate-eligible)
 - [ ] All outputs are valid and readable
 
 ---
@@ -584,7 +607,7 @@ Knowledge fragments referenced:
 **Phase 1 (Traceability):**
 
 - [ ] All prerequisites met
-- [ ] All acceptance criteria mapped or gaps documented
+- [ ] All oracle items mapped or gaps documented
 - [ ] P0 coverage is 100% OR documented as BLOCKER
 - [ ] Gap analysis is complete and prioritized
 - [ ] Test quality issues identified and flagged
@@ -595,7 +618,8 @@ Knowledge fragments referenced:
 - [ ] All quality evidence gathered
 - [ ] Decision criteria applied correctly
 - [ ] Decision rationale documented
-- [ ] Gate YAML ready for CI/CD integration
+- [ ] `e2e-trace-summary.json` written and valid JSON
+- [ ] `gate-decision.json` written when gate-eligible
 - [ ] Status file updated (if enabled)
 - [ ] Stakeholders notified (if enabled)