bmad-method-test-architecture-enterprise 1.5.2 → 1.6.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method-test-architecture-enterprise",
-  "version": "1.5.2",
+  "version": "1.6.0",
   "description": "Master Test Architect for quality strategy, test automation, and release gates",
   "keywords": [
     "bmad",

package/release_notes.md

@@ -1,13 +1,13 @@
-## 🚀 What's New in v1.5.2
+## 🚀 What's New in v1.6.0
 
 ### ✨ New Features
-- feat: harden pact framework and knowledge
-
-### 🐛 Bug Fixes
-- fix: pr comments
+- feat: refine pactjs automate
 
 ### 📦 Other Changes
-- Merge pull request #51 from bmad-code-org/feat/harden-pact-framework-flow
+- pactjs knowledge base refinements
+- addressed PR comments
+- addressed augment comments
+- Merge pull request #53 from bmad-code-org/feat/refine-pactjs-automate
 
 
 ## 📦 Installation
@@ -17,4 +17,4 @@ npx bmad-method install
 # Select "Test Architect" from module menu
 ```
 
-**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.5.1...v1.5.2
+**Full Changelog**: https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/compare/v1.5.3...v1.6.0

package/src/testarch/knowledge/ci-burn-in.md

@@ -714,4 +714,4 @@ Before deploying your CI pipeline, verify:
 - Related fragments: `selective-testing.md`, `playwright-config.md`, `test-quality.md`
 - CI tools: GitHub Actions, GitLab CI, CircleCI, Jenkins
 
-_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples, SEON production pipelines_
+_Source: Murat CI/CD strategy blog, Playwright/Cypress workflow examples, enterprise production pipelines_

package/src/testarch/knowledge/contract-testing.md

@@ -130,7 +130,7 @@ describe('User API Contract', () => {
             'Content-Type': 'application/json',
             Accept: 'application/json',
           },
-          body: like(newUser),
+          body: newUser,
         })
         .willRespondWith({
           status: 201,
@@ -176,7 +176,7 @@ describe('User API Contract', () => {
 **Key Points**:
 
 - **Consumer-driven**: Frontend defines expectations, not backend
-- **Matchers**: `like`, `string`, `integer` for flexible matching
+- **Matchers (Postel's Law)**: Use `like`, `string`, `integer` matchers in `willRespondWith` (responses) for flexible matching. Do NOT use `like()` on request bodies in `withRequest` — the consumer controls what it sends, so request bodies should use exact values. This follows Postel's Law: be strict in what you send (requests), be lenient in what you accept (responses).
 - **Provider states**: given() sets up test preconditions
 - **Isolation**: No real backend needed, runs fast
 - **Pact generation**: Automatically creates JSON pact files
@@ -944,6 +944,67 @@ jobs:
 
 ---
 
+## Provider Scrutiny Protocol
+
+When generating consumer contract tests, the agent **MUST** analyze provider source code — or the provider's OpenAPI/Swagger spec — before writing any Pact interaction. Generating contracts from consumer-side assumptions alone leads to mismatches that only surface during provider verification — wrong response shapes, wrong status codes, wrong field names, wrong types, missing required fields, and wrong enum values.
+
+**Source priority**: Provider source code is the most authoritative reference. When an OpenAPI/Swagger spec exists (`openapi.yaml`, `openapi.json`, `swagger.json`), use it as a complementary or alternative source — it documents the provider's contract explicitly and can be faster to parse than tracing through handler code. When both exist, cross-reference them; if they disagree, the source code wins.
+
+### Provider Endpoint Comment
+
+Every Pact interaction MUST include a provider endpoint comment immediately above the `.given()` call:
+
+```typescript
+// Provider endpoint: server/src/routes/userRouteHandlers.ts -> GET /api/v2/users/:userId
+await provider.given('user with id 1 exists').uponReceiving('a request for user 1');
+```
+
+**Format**: `// Provider endpoint: <relative-path-to-handler> -> <METHOD> <route-pattern>`
+
+If the provider source is not accessible, use: `// Provider endpoint: TODO — provider source not accessible, verify manually`
+
+### Seven-Point Scrutiny Checklist
+
+Before generating each Pact interaction, read the provider route handler and/or OpenAPI spec and verify:
+
+| #   | Check                 | What to Read (source code / OpenAPI spec)                         | Common Mismatch                                               |
+| --- | --------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------- |
+| 1   | **Response shape**    | Handler's `res.json()` calls / OpenAPI `responses.content.schema` | Nested object vs flat; array wrapper vs direct                |
+| 2   | **Status codes**      | Handler's `res.status()` calls / OpenAPI `responses` keys         | 200 vs 201 for creation; 204 vs 200 for delete                |
+| 3   | **Field names**       | Response type/DTO definitions / OpenAPI `schema.properties`       | `transaction_id` vs `transactionId`; `fraud_score` vs `score` |
+| 4   | **Enum values**       | Validation schemas, constants / OpenAPI `schema.enum`             | `"active"` vs `"ACTIVE"`; `"pending"` vs `"in_progress"`      |
+| 5   | **Required fields**   | Request validation (Joi, Zod) / OpenAPI `schema.required`         | Missing required header; optional field assumed required      |
+| 6   | **Data types**        | TypeScript types, DB models / OpenAPI `schema.type` + `format`    | `string` ID vs `number` ID; ISO date vs Unix timestamp        |
+| 7   | **Nested structures** | Response builder, serializer / OpenAPI `$ref` + `allOf`/`oneOf`   | `{ data: { items: [] } }` vs `{ items: [] }`                  |
+
+### Scrutiny Evidence Block
+
+Document what was found from provider source and/or OpenAPI spec as a block comment in the test file:
+
+```typescript
+/*
+ * Provider Scrutiny Evidence:
+ * - Handler: server/src/routes/userRouteHandlers.ts:45
+ * - OpenAPI: server/openapi.yaml paths./api/v2/users/{userId}.get (if available)
+ * - Response type: UserResponseDto (server/src/types/user.ts:12)
+ * - Status: 200 (line 52), 404 (line 48)
+ * - Fields: { id: number, name: string, email: string, role: "user" | "admin", createdAt: string }
+ * - Required request headers: Authorization (Bearer token)
+ * - Validation: Zod schema at server/src/validation/user.ts:8
+ */
+```
+
+### Graceful Degradation
+
+When provider source code is not accessible (different repo, no access, closed source):
+
+1. **OpenAPI/Swagger spec available**: Use the spec as the source of truth for response shapes, status codes, and field names
+2. **Pact Broker has existing contracts**: Use `pact_mcp` tools to fetch existing provider states and verified interactions as reference
+3. **Neither available**: Generate contracts from consumer-side types but use the TODO form of the mandatory comment: `// Provider endpoint: TODO — provider source not accessible, verify manually` and add a `provider_scrutiny: "pending"` field to the output JSON
+4. **Never silently guess**: If you cannot verify, document what you assumed and why
+
+---
+
 ## Contract Testing Checklist
 
 Before implementing contract testing, verify:
@@ -956,6 +1017,9 @@ Before implementing contract testing, verify:
 - [ ] **Webhooks configured**: Consumer changes trigger provider verification
 - [ ] **Retention policy**: Old pacts archived (keep 30 days, all production tags)
 - [ ] **Resilience tested**: Timeouts, retries, error codes in contracts
+- [ ] **Provider endpoint comments**: Every Pact interaction has `// Provider endpoint:` comment
+- [ ] **Provider scrutiny completed**: Seven-point checklist verified for each interaction
+- [ ] **Scrutiny evidence documented**: Block comment with handler, types, status codes, and fields
 
 ## Integration Points
 

package/src/testarch/knowledge/error-handling.md

@@ -722,4 +722,4 @@ Before shipping error handling code, verify:
 - Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
 - Monitoring tools: Sentry, Datadog, LogRocket
 
-_Source: Murat error-handling patterns, Pact resilience guidance, SEON production error handling_
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_

package/src/testarch/knowledge/feature-flags.md

@@ -747,4 +747,4 @@ Before merging flag-related code, verify:
 - Related fragments: `test-quality.md`, `selective-testing.md`
 - Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
 
-_Source: LaunchDarkly strategy blog, Murat test architecture notes, SEON feature flag governance_
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_

package/src/testarch/knowledge/fixture-architecture.md

@@ -398,4 +398,4 @@ When deciding whether to create a fixture, follow these rules:
 - **1 use** → Keep inline (avoid premature abstraction)
 - **Complex logic** → Factory function pattern (dynamic data generation)
 
-_Source: Murat Testing Philosophy (lines 74-122), SEON production patterns, Playwright fixture docs._
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._

package/src/testarch/knowledge/network-recorder.md

@@ -304,13 +304,13 @@ await networkRecorder.setup(context, {
   playback: {
     urlMapping: {
       hostMapping: {
-        'localhost:3000': 'admin.seondev.space',
-        'admin-staging.seon.io': 'admin.seondev.space',
-        'admin.seon.io': 'admin.seondev.space',
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
       },
       patterns: [
-        { match: /admin-\d+\.seondev\.space/, replace: 'admin.seondev.space' },
-        { match: /admin-staging-pr-\w+-\d\.seon\.io/, replace: 'admin.seondev.space' },
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
       ],
     },
   },

package/src/testarch/knowledge/overview.md

@@ -15,7 +15,7 @@ Writing Playwright utilities from scratch for every project leads to:
 
 `@seontechnologies/playwright-utils` provides:
 
-- **Production-tested utilities**: Used at SEON Technologies in production
+- **Production-tested**: Used in enterprise production environments
 - **Functional-first design**: Core logic as pure functions, fixtures for convenience
 - **Composable fixtures**: Use `mergeTests` to combine utilities
 - **TypeScript support**: Full type safety with generic types

package/src/testarch/knowledge/pact-consumer-di.md

@@ -4,7 +4,7 @@
 
 Inject the Pact mock server URL into consumer code via an optional `baseUrl` field on the API context type instead of using raw `fetch()` inside `executeTest()`. This ensures contract tests exercise the real consumer HTTP client — including retry logic, header assembly, timeout configuration, error handling, and metrics — rather than testing Pact itself.
 
-The base URL is typically a module-level constant evaluated at import time (`export const API_BASE_URL = env.SEON_API_URL`), but `mockServer.url` is only available at runtime inside `executeTest()`. Dependency injection solves this timing mismatch cleanly: add one optional field to the context type, use nullish coalescing in the HTTP client factory, and inject the mock server URL in tests.
+The base URL is typically a module-level constant evaluated at import time (`export const API_BASE_URL = env.API_BASE_URL`), but `mockServer.url` is only available at runtime inside `executeTest()`. Dependency injection solves this timing mismatch cleanly: add one optional field to the context type, use nullish coalescing in the HTTP client factory, and inject the mock server URL in tests.
 
 ## Rationale
 
@@ -124,7 +124,7 @@ export function createTestContext(mockServerUrl: string): ApiContext {
 
 ```typescript
 .executeTest(async (mockServer: V3MockServer) => {
-  const api = createSeonApi(createTestContext(mockServer.url));
+  const api = createApiClient(createTestContext(mockServer.url));
   const result = await api.getFilterFields();
   expect(result).toEqual(
     expect.arrayContaining([
@@ -277,7 +277,7 @@ expect(response.status).toBe(200);
 
 ```typescript
 // GOOD: Exercises real client, validates parsed return value
-const api = createSeonApi(createTestContext(mockServer.url));
+const api = createApiClient(createTestContext(mockServer.url));
 const result = await api.searchTransactions(request);
 expect(result.transactions).toBeDefined();
 ```
@@ -307,4 +307,4 @@ Used in workflows:
 
 ## Source
 
-Pattern derived from seon-mcp-server Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.

package/src/testarch/knowledge/pact-consumer-framework-setup.md

@@ -418,15 +418,15 @@ describe('Movies API Consumer Contract', () => {
       )
       .willRespondWith(
         200,
-        setJsonContent({
-          body: like({
+        setJsonBody(
+          like({
             id: integer(1),
             name: string('The Matrix'),
             year: integer(1999),
             rating: like(8.7),
             director: string('Wachowskis'),
           }),
-        }),
+        ),
       )
       .executeTest(async (mockServer: V3MockServer) => {
         // Inject mock server URL into the REAL consumer code
@@ -463,6 +463,7 @@ describe('Movies API Consumer Contract', () => {
 - Consumer code MUST expose a URL injection mechanism: `setApiUrl()`, env var override, or constructor parameter
 - If the consumer code doesn't support URL injection, add it — this is a design prerequisite for CDC testing
 - Use PactV4 `addInteraction()` builder (not PactV3 fluent API with `withRequest({...})` object)
+- **Interaction naming convention**: Use the pattern `"a request to <action> <resource> [<condition>]"` for `uponReceiving()`. Examples: `"a request to get a movie by ID"`, `"a request to delete a non-existing movie"`, `"a request to create a movie that already exists"`. These names appear in Pact Broker UI and verification logs — keep them descriptive and unique within the consumer-provider pair.
 - Use `setJsonContent` for request/response builder callbacks with query/header/body concerns; use `setJsonBody` for body-only response callbacks
 - Provider state factory functions (`movieExists`) return `ProviderStateInput` objects
 - `createProviderState` converts to `[stateName, stateParams]` tuple for `.given()`
@@ -616,7 +617,10 @@ Before presenting the consumer CDC framework to the user, verify:
 - [ ] `.github/actions/detect-breaking-change/action.yml` exists
 - [ ] Consumer tests use `.pacttest.ts` extension
 - [ ] Consumer tests use PactV4 `addInteraction()` builder
+- [ ] `uponReceiving()` names follow `"a request to <action> <resource> [<condition>]"` pattern and are unique within the consumer-provider pair
 - [ ] Interaction callbacks use `setJsonContent` for query/header/body and `setJsonBody` for body-only responses
+- [ ] Request bodies use exact values (no `like()` wrapper) — Postel's Law: be strict in what you send
+- [ ] `like()`, `eachLike()`, `string()`, `integer()` matchers are only used in `willRespondWith` (responses), not in `withRequest` (requests) — matchers check type/shape, not exact values
 - [ ] Consumer tests call REAL consumer code (actual API client functions), NOT raw `fetch()`
 - [ ] Consumer code exposes URL injection mechanism (`setApiUrl()`, env var, or constructor param)
 - [ ] Local consumer-helpers shim present if pactjs-utils not installed

package/src/testarch/knowledge/pactjs-utils-consumer-helpers.md

@@ -196,6 +196,8 @@ await pact
 - **Message pacts**: Works identically with `MessageConsumerPact` — same `.given()` API
 - **Builder reuse**: `setJsonContent` works for both `.withRequest(...)` and `.willRespondWith(...)` callbacks (query is ignored on response builders)
 - **Body shorthand**: `setJsonBody` keeps body-only responses concise and readable
+- **Matchers check type, not value**: `string('My movie')` means "any string", `integer(1)` means "any integer". The example values are arbitrary — the provider can return different values and verification still passes as long as the type matches. Use matchers only in `.willRespondWith()` (responses), never in `.withRequest()` (requests) — Postel's Law applies.
+- **Reuse test values across files**: Interactions are uniquely identified by `uponReceiving` + `.given()`, not by placeholder values. Two test files can both use `testId: 100` without conflicting. On the provider side, shared values simplify state handlers — idempotent handlers (check if exists, create if not) only need to ensure one record exists. Use different values only when testing different states of the same entity type (e.g., `movieExists(100)` for happy paths vs. `movieNotFound(999)` for error paths).
 
 ## Related Fragments
 

package/src/testarch/knowledge/playwright-config.md

@@ -727,4 +727,4 @@ jobs:
 - [ ] Projects defined for cross-browser/device testing (if needed)
 - [ ] CI uploads artifacts on failure with 30-day retention
 
-_Source: Playwright book repo, SEON configuration example, Murat testing philosophy (lines 216-271)._
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._

package/src/testarch/knowledge/risk-governance.md

@@ -612,4 +612,4 @@ Before deploying to production, ensure:
 - **Related fragments**: `probability-impact.md` (scoring definitions), `test-priorities-matrix.md` (P0-P3 classification), `nfr-criteria.md` (non-functional risks)
 - **Tools**: Risk tracking dashboards (Jira, Linear), gate automation (CI/CD), traceability reports (Markdown, Confluence)
 
-_Source: Murat risk governance notes, gate schema guidance, SEON production gate workflows, ISO 31000 risk management standards_
+_Source: Murat risk governance notes, gate schema guidance, enterprise production gate workflows, ISO 31000 risk management standards_

package/src/testarch/knowledge/selective-testing.md

@@ -728,5 +728,5 @@ Before implementing selective testing, verify:
 - Related fragments: `ci-burn-in.md`, `test-priorities-matrix.md`, `test-quality.md`
 - Selection tools: Playwright --grep, Cypress @cypress/grep, git diff
 
-_Source: 32+ selective testing strategies blog, Murat testing philosophy, SEON CI optimization_
+_Source: 32+ selective testing strategies blog, Murat testing philosophy, enterprise CI optimization_
 ```

package/src/testarch/knowledge/visual-debugging.md

@@ -521,4 +521,4 @@ Before deploying tests to CI, ensure:
 - **Related fragments**: `playwright-config.md` (artifact configuration), `ci-burn-in.md` (CI artifact upload), `test-quality.md` (debugging best practices)
 - **Tools**: Playwright Trace Viewer, Cypress Debug UI, axe-core, HAR files
 
-_Source: Playwright official docs, Murat testing philosophy (visual debugging manifesto), SEON production debugging patterns_
+_Source: Playwright official docs, Murat testing philosophy (visual debugging manifesto), enterprise production debugging patterns_

package/src/workflows/testarch/atdd/steps-c/step-04-generate-tests.md

@@ -71,9 +71,12 @@ const subagentContext = {
   config: {
     test_framework: config.test_framework,
     use_playwright_utils: config.tea_use_playwright_utils,
+    use_pactjs_utils: config.tea_use_pactjs_utils,
+    pact_mcp: config.tea_pact_mcp,  // "mcp" | "none"
     browser_automation: config.tea_browser_automation,
     execution_mode: config.tea_execution_mode || 'auto',  // "auto" | "subagent" | "agent-team" | "sequential"
     capability_probe: parseBooleanFlag(config.tea_capability_probe, true),  // supports booleans and "false"/"true" strings
+    provider_endpoint_map: /* from Step 1/3 context, if use_pactjs_utils enabled */,
   },
   timestamp: timestamp
 };

package/src/workflows/testarch/atdd/steps-c/step-04a-subagent-api-failing.md

@@ -16,7 +16,8 @@ This is an **isolated subagent** running in parallel with E2E failing test gener
 - Story acceptance criteria from Step 1
 - Test strategy and scenarios from Step 3
 - Knowledge fragments loaded: api-request, data-factories, api-testing-patterns
-- Config: test framework, Playwright Utils enabled/disabled
+- Config: test framework, Playwright Utils enabled/disabled, Pact.js Utils enabled/disabled (`use_pactjs_utils`), Pact MCP mode (`pact_mcp`)
+- Provider Endpoint Map (if `use_pactjs_utils` enabled and provider source accessible)
 
 **Your task:** Generate API tests that will FAIL because the feature is not implemented yet (TDD RED PHASE).
 
@@ -113,6 +114,72 @@ test.describe('[Story Name] API Tests (ATDD)', () => {
 - ✅ Use data factories for test data (from data-factories fragment)
 - ✅ Include priority tags [P0], [P1], [P2], [P3]
 
+### 1.5 Provider Source Scrutiny for CDC in TDD Red Phase (If `use_pactjs_utils` Enabled)
+
+When generating Pact consumer contract tests in the ATDD red phase, provider scrutiny applies with TDD-specific rules. Apply the **Seven-Point Scrutiny Checklist** from `contract-testing.md` (Response shape, Status codes, Field names, Enum values, Required fields, Data types, Nested structures) for both existing and new endpoints.
+
+**If provider endpoint already exists** (extending an existing API):
+
+- READ the provider route handler, types, and validation schemas
+- Verify all seven scrutiny points against the provider source: Response shape, Status codes, Field names, Enum values, Required fields, Data types, Nested structures
+- Add `// Provider endpoint:` comment and scrutiny evidence block documenting findings for each point
+- Wrap the entire test function in `test.skip()` (so the whole test including `executeTest` is skipped), not just the callback
+
+**If provider endpoint is new** (TDD — endpoint not implemented yet):
+
+- Use acceptance criteria as the source of truth for expected behavior
+- Acceptance criteria should specify all seven scrutiny points where possible (status codes, field names, types, etc.) — note any gaps as assumptions in the evidence block
+- Add `// Provider endpoint: TODO — new endpoint, not yet implemented`
+- Document expected behavior from acceptance criteria in scrutiny evidence block
+- Wrap the entire test function in `test.skip()` and use realistic expectations from the story
+
+**Graceful degradation when provider source is inaccessible:**
+
+1. **OpenAPI/Swagger spec available**: Use the spec as the source of truth for response shapes, status codes, and field names
+2. **Pact Broker available** (when `pact_mcp` is `"mcp"`): Use SmartBear MCP tools to fetch existing provider states and verified interactions as reference
+3. **Neither available**: For new endpoints, use acceptance criteria; for existing endpoints, use consumer-side types. Mark with `// Provider endpoint: TODO — provider source not accessible, verify manually` and set `provider_scrutiny: "pending"` in output JSON
+4. **Never silently guess**: Document all assumptions in the scrutiny evidence block
+
+**Provider endpoint comments are MANDATORY** even in red-phase tests — they document the intent.
+
+**Example: Red-phase Pact test with provider scrutiny:**
+
+```typescript
+// Provider endpoint: TODO — new endpoint, not yet implemented
+/*
+ * Provider Scrutiny Evidence:
+ * - Handler: NEW — not yet implemented (TDD red phase)
+ * - Expected from acceptance criteria:
+ *   - Endpoint: POST /api/v2/users/register
+ *   - Status: 201 for success, 400 for duplicate email, 422 for validation error
+ *   - Response: { id: number, email: string, createdAt: string }
+ */
+test.skip('[P0] should generate consumer contract for user registration', async () => {
+  await provider
+    .given('no users exist')
+    .uponReceiving('a request to register a new user')
+    .withRequest({
+      method: 'POST',
+      path: '/api/v2/users/register',
+      headers: { 'Content-Type': 'application/json' },
+      body: { email: 'newuser@example.com', password: 'SecurePass123!' },
+    })
+    .willRespondWith({
+      status: 201,
+      headers: { 'Content-Type': 'application/json' },
+      body: like({
+        id: integer(1),
+        email: string('newuser@example.com'),
+        createdAt: string('2025-01-15T10:00:00Z'),
+      }),
+    })
+    .executeTest(async (mockServer) => {
+      const result = await registerUser({ email: 'newuser@example.com', password: 'SecurePass123!' }, { baseUrl: mockServer.url });
+      expect(result.id).toEqual(expect.any(Number));
+    });
+});
+```
+
 **Why test.skip():**
 
 - Tests are written correctly for EXPECTED behavior
@@ -163,6 +230,7 @@ Write JSON to temp file: `/tmp/tea-atdd-api-tests-{{timestamp}}.json`
   "knowledge_fragments_used": ["api-request", "data-factories", "api-testing-patterns"],
   "test_count": 3,
   "tdd_phase": "RED",
+  "provider_scrutiny": "completed",
   "summary": "Generated 3 FAILING API tests for user registration story"
 }
 ```
@@ -205,6 +273,8 @@ Subagent completes when:
 - JSON output valid and complete
 - No E2E/component/unit tests included (out of scope)
 - Tests follow knowledge fragment patterns
+- Every Pact interaction has `// Provider endpoint:` comment (if CDC enabled)
+- Provider scrutiny completed or TODO markers added for new endpoints (if CDC enabled)
 
 ### ❌ FAILURE:
 
@@ -213,3 +283,4 @@ Subagent completes when:
 - Placeholder assertions (expect(true).toBe(true))
 - Did not follow knowledge fragment patterns
 - Invalid or missing JSON output
+- Pact interactions missing provider endpoint comments (if CDC enabled)

package/src/workflows/testarch/automate/checklist.md

@@ -191,6 +191,33 @@ Before starting this workflow, verify:
 - [ ] Error cases tested (400, 401, 403, 404, 500)
 - [ ] JWT token format validated (if auth tests)
 
+### Consumer Contract Tests / CDC (If `use_pactjs_utils` Enabled)
+
+**Provider Endpoint Comments:**
+
+- [ ] Every Pact interaction has `// Provider endpoint:` comment
+- [ ] Comment includes exact file path to provider route handler, OR uses the TODO form when provider is inaccessible
+- [ ] Comment follows format: `// Provider endpoint: <path> -> <METHOD> <route>` or `// Provider endpoint: TODO — provider source not accessible, verify manually`
+
+**Provider Source Scrutiny:**
+
+- [ ] Provider route handlers and/or OpenAPI spec read before generating each interaction
+- [ ] Status codes verified against provider source (e.g., 201 not assumed 200)
+- [ ] Field names cross-referenced with provider type/DTO definitions
+- [ ] Data types verified (string ID vs number ID, date formats)
+- [ ] Enum/union values extracted from provider validation schemas
+- [ ] Required request fields and headers checked against provider validation
+- [ ] Nested response structures match provider's actual response construction
+- [ ] Scrutiny evidence documented as block comment in each test file
+
+**CDC Quality Gates:**
+
+- [ ] Postel's Law enforced: exact values in `withRequest`, matchers in `willRespondWith`
+- [ ] Response matchers (`like`, `eachLike`, `string`, `integer`) used only in `willRespondWith`
+- [ ] Provider state names are consistent with provider's state handler naming
+- [ ] DI pattern used for consumer function imports (actual consumer code, not raw `fetch()`)
+- [ ] One logical endpoint per Pact interaction (no multi-endpoint interactions)
+
 ### Component Tests (If Applicable)
 
 - [ ] Component test files created in `tests/component/`
@@ -467,6 +494,8 @@ All of the following must be true before marking this workflow as complete:
 - [ ] **Output file formatted correctly**
 - [ ] **Knowledge base references applied** and documented (including healing fragments if used)
 - [ ] **No test quality issues** (flaky patterns, race conditions, hardcoded data, page objects)
+- [ ] **Provider scrutiny completed or gracefully degraded** for all CDC interactions — each interaction either has scrutiny evidence or a TODO marker (if `use_pactjs_utils` enabled)
+- [ ] **Provider endpoint comments present** on every Pact interaction (if `use_pactjs_utils` enabled)
 
 ---
 

package/src/workflows/testarch/automate/steps-c/step-02-identify-targets.md

@@ -77,6 +77,30 @@ Use CLI to explore the application and identify testable pages/flows:
 
 ---
 
+**If `use_pactjs_utils` is enabled — Provider Endpoint Mapping (all stacks):**
+
+When consumer-driven contract tests will be generated, build a Provider Endpoint Map during target identification. This applies to all `{detected_stack}` values — frontend, backend, and fullstack consumers all need provider scrutiny.
+
+1. **Locate provider source and/or OpenAPI spec**: Scan workspace for provider project (from config, monorepo structure, or adjacent repositories). Also check for OpenAPI/Swagger spec files (`openapi.yaml`, `openapi.json`, `swagger.json`) — these document the provider's contract explicitly and can supplement or replace handler code analysis.
+2. **Map each consumer endpoint** to its provider counterpart:
+   - Provider file path (route handler)
+   - Route pattern (METHOD + path)
+   - Validation schema location (Joi, Zod, class-validator) or OpenAPI request schema
+   - Response type/DTO definition location or OpenAPI response schema
+   - OpenAPI spec path (if available, e.g., `server/openapi.yaml`)
+3. **Output as "Provider Endpoint Map" table** in the coverage plan:
+
+```markdown
+| Consumer Endpoint     | Provider File                     | Route                     | Validation Schema                   | Response Type   | OpenAPI Spec                                      |
+| --------------------- | --------------------------------- | ------------------------- | ----------------------------------- | --------------- | ------------------------------------------------- |
+| GET /api/v2/users/:id | server/src/routes/userHandlers.ts | GET /api/v2/users/:userId | server/src/validation/user.ts       | UserResponseDto | server/openapi.yaml#/paths/~1api~1v2~1users~1{id} |
+| POST /api/v2/users    | server/src/routes/userHandlers.ts | POST /api/v2/users        | server/src/validation/createUser.ts | UserResponseDto | server/openapi.yaml#/paths/~1api~1v2~1users       |
+```
+
+4. **If provider source not accessible**: Mark entries with `TODO — provider source not accessible` and note in coverage plan that provider scrutiny will use graceful degradation (see `contract-testing.md` Provider Scrutiny Protocol)
+
+---
+
 ## 2. Choose Test Levels
 
 Use `test-levels-framework.md` to select:

package/src/workflows/testarch/automate/steps-c/step-03-generate-tests.md

@@ -74,6 +74,7 @@ const subagentContext = {
     detected_stack: '{detected_stack}',  // "frontend" | "backend" | "fullstack"
     execution_mode: config.tea_execution_mode || 'auto',  // "auto" | "subagent" | "agent-team" | "sequential"
     capability_probe: parseBooleanFlag(config.tea_capability_probe, true),  // supports booleans and "false"/"true" strings
+    provider_endpoint_map: /* from Step 2 coverage plan, if use_pactjs_utils enabled */,
   },
   timestamp: timestamp
 };
@@ -190,6 +191,7 @@ When `use_pactjs_utils` is enabled, the API test generation subagent (step-03a)
 - **Provider verification tests**: Using `buildVerifierOptions` for one-call verifier setup
 - **Message contract tests**: Using `buildMessageVerifierOptions` if async/Kafka patterns detected
 - **Helper files**: Request filter setup with `createRequestFilter`, shared state constants
+- **Provider scrutiny**: Subagent reads provider route handlers, types, and validation schemas before generating each interaction (see `contract-testing.md` Provider Scrutiny Protocol)
 
 When `pact_mcp` is `"mcp"`, the subagent can use SmartBear MCP tools to fetch existing provider states and generate tests informed by broker data.
 

package/src/workflows/testarch/automate/steps-c/step-03a-subagent-api.md

@@ -97,6 +97,69 @@ test.describe('[Feature] API Tests', () => {
 - ✅ Generate request filter helpers in `pact/http/helpers/` using `createRequestFilter({ tokenGenerator: () => string })`
 - ✅ Generate shared state constants in `pact/http/helpers/states.ts`
 - ✅ If async/message patterns detected, generate message consumer tests in `pact/message/` using `buildMessageVerifierOptions`
+- ✅ **Provider endpoint comment MANDATORY** on every Pact interaction: `// Provider endpoint: <path> -> <METHOD> <route>`
+- ⚠️ **Postel's Law for matchers**: Use `like()`, `eachLike()`, `string()`, `integer()` matchers ONLY in `willRespondWith` (responses). Request bodies in `withRequest` MUST use exact values — never wrap request bodies in `like()`. The consumer controls what it sends, so contracts should be strict about request shape.
+
+### 1.5 Provider Source Scrutiny (CDC Only)
+
+**CRITICAL**: Before generating ANY Pact consumer interaction, perform provider source scrutiny per the **Seven-Point Scrutiny Checklist** defined in `contract-testing.md`. Do NOT generate response matchers from consumer-side types alone — this is the #1 cause of contract verification failures.
+
+The seven points to verify for each interaction:
+
+1. Response shape
+2. Status codes
+3. Field names
+4. Enum values
+5. Required fields
+6. Data types
+7. Nested structures
+
+**Source priority**: Provider source code is most authoritative. When an OpenAPI/Swagger spec exists (`openapi.yaml`, `openapi.json`, `swagger.json`), use it as a complementary or alternative source — it documents the provider's contract explicitly and can be faster to parse than tracing through handler code. When both exist, cross-reference them; if they disagree, the source code wins. Document the discrepancy in the scrutiny evidence block (e.g., `OpenAPI shows 200 but handler returns 201; using handler behavior`) and flag it in the output JSON `summary` so it is discoverable by downstream consumers or audits.
+
+**Scrutiny Sequence** (for each endpoint in the coverage plan):
+
+1. **READ provider route handler and/or OpenAPI spec**: Find the handler file from `subagentContext.config.provider_endpoint_map` or by scanning the provider codebase. Also check for OpenAPI/Swagger spec files. Extract:
+   - Exact status codes returned (`res.status(201)` / OpenAPI `responses` keys)
+   - Response construction (`res.json({ data: ... })` / OpenAPI `schema`)
+   - Error handling paths (what status codes for what conditions)
+
+2. **READ provider type/model/DTO definitions**: Find the response type referenced by the handler or OpenAPI `$ref` schemas. Extract:
+   - Exact field names (`transaction_id` not `transactionId`)
+   - Field types (`string` ID vs `number` ID / OpenAPI `type` + `format`)
+   - Optional vs required fields (OpenAPI `required` array)
+   - Nested object structures (OpenAPI `$ref`, `allOf`, `oneOf`)
+
+3. **READ provider validation schemas**: Find Joi/Zod/class-validator schemas or OpenAPI request body `schema.required`. Extract:
+   - Required request fields and headers
+   - Enum/union type allowed values (`"active" | "inactive"` / OpenAPI `enum`)
+   - Request body constraints
+
+4. **Cross-reference findings** against consumer expectations:
+   - Does the consumer expect the same field names the provider sends?
+   - Does the consumer expect the same status codes the provider returns?
+   - Does the consumer expect the same nesting the provider produces?
+
+5. **Document scrutiny evidence** as a block comment in the generated test:
+
+```typescript
+/*
+ * Provider Scrutiny Evidence:
+ * - Handler: server/src/routes/userHandlers.ts:45
+ * - OpenAPI: server/openapi.yaml paths./api/v2/users/{userId}.get (if available)
+ * - Response type: UserResponseDto (server/src/types/user.ts:12)
+ * - Status: 201 for creation (line 52), 400 for validation error (line 48)
+ * - Fields: { id: number, name: string, email: string, role: "user" | "admin" }
+ * - Required request headers: Authorization (Bearer token)
+ */
+```
+
+6. **Graceful degradation** when provider source is not accessible (follows the canonical four-step protocol from `contract-testing.md`):
+   1. **OpenAPI/Swagger spec available**: Use the spec as the source of truth for response shapes, status codes, and field names
+   2. **Pact Broker available** (when `pact_mcp` is `"mcp"` in `subagentContext.config`): Use SmartBear MCP tools to fetch existing provider states and verified interactions as reference
+   3. **Neither available**: Generate from consumer types but use the TODO form of the mandatory comment: `// Provider endpoint: TODO — provider source not accessible, verify manually`. Set `provider_scrutiny: "pending"` in output JSON
+   4. **Never silently guess**: Document all assumptions in the scrutiny evidence block
+
+> ⚠️ **Anti-pattern**: Generating response matchers from consumer-side types alone. This produces contracts that reflect what the consumer _wishes_ the provider returns, not what it _actually_ returns. Always read provider source or OpenAPI spec first.
 
 ### 3. Track Fixture Needs
 
@@ -144,6 +207,8 @@ Write JSON to temp file: `/tmp/tea-automate-api-tests-{{timestamp}}.json`
   ],
   "fixture_needs": ["authToken", "userDataFactory", "productDataFactory"],
   "knowledge_fragments_used": ["api-request", "data-factories", "api-testing-patterns"],
+  "provider_scrutiny": "completed",
+  "provider_files_read": ["server/src/routes/authHandlers.ts", "server/src/routes/checkoutHandlers.ts", "server/src/types/auth.ts"],
   "test_count": 12,
   "summary": "Generated 12 API test cases covering 3 features"
 }
@@ -184,6 +249,9 @@ Subagent completes when:
 - All API tests generated following patterns
 - JSON output valid and complete
 - No E2E/component/unit tests included (out of scope)
+- Every Pact interaction has `// Provider endpoint:` comment (if CDC enabled)
+- Provider source scrutiny completed or gracefully degraded with TODO markers (if CDC enabled)
+- Scrutiny evidence documented as block comments in test files (if CDC enabled)
 
 ### ❌ FAILURE:
 
@@ -191,3 +259,5 @@ Subagent completes when:
 - Did not follow knowledge fragment patterns
 - Invalid or missing JSON output
 - Ran tests (not subagent responsibility)
+- Pact interactions missing provider endpoint comments (if CDC enabled)
+- Response matchers generated from consumer-side types without provider scrutiny (if CDC enabled)