froid-plane-test-architecture-enterprise 1.23.4

package/src/agents/froid-tea/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/src/agents/froid-tea/resources/tea-index.csv

@@ -0,0 +1,60 @@
+id,name,description,tags,tier,fragment_file
+library-integration-mandate,Library Integration Mandate,"General contract for every TEA integration library flag: the two gates (flag true plus package installed), REQUIRED vs RECOMMENDED levels, deviation protocol, scope discipline, the flag-to-mandate registry, and the ten places a new library must be wired","standards,governance,generation,review,integration,mandate",core,knowledge/library-integration-mandate.md
+fixture-architecture,Fixture Architecture,"Composable fixture patterns (pure function → fixture → merge) and reuse rules","fixtures,architecture,playwright,cypress",core,knowledge/fixture-architecture.md
+network-first,Network-First Safeguards,"Intercept-before-navigate workflow, HAR capture, deterministic waits, edge mocking","network,stability,playwright,cypress,ui",core,knowledge/network-first.md
+data-factories,Data Factories and API Setup,"Factories with overrides, API seeding, cleanup discipline, and naming the domain literals a test hardcodes on purpose","data,factories,setup,api,backend,seeding,magic-value,literals,naming,constants",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions, and user-level interaction over raw event dispatch","component-testing,tdd,ui,user-event,fire-event,interaction",extended,knowledge/component-tdd.md
+playwright-config,Playwright Config Guardrails,"Environment switching, timeout standards, artifact outputs","playwright,config,env",extended,knowledge/playwright-config.md
+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, 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
+risk-governance,Risk Governance,"Scoring matrix, category ownership, gate decision rules","risk,governance,gates",core,knowledge/risk-governance.md
+probability-impact,Probability and Impact Scale,"Shared definitions for scoring matrix and gate thresholds","risk,scoring,scale",core,knowledge/probability-impact.md
+test-quality,Test Quality Definition of Done,"Execution limits, isolation rules, green criteria, committed skips and focus, assertions that cannot fail, and suite structure and naming","quality,definition-of-done,tests,skip,only,focused,disabled,tautological,assertions,mocks,unreachable,concerns,grouping,nesting,naming,assertion-style",core,knowledge/test-quality.md
+nfr-criteria,NFR Review Criteria,"Security, performance, reliability, maintainability status definitions","nfr,assessment,quality",extended,knowledge/nfr-criteria.md
+test-levels,Test Levels Framework,"Guidelines for choosing unit, integration, or end-to-end coverage","testing,levels,selection,api,backend,ui",core,knowledge/test-levels-framework.md
+test-priorities,Test Priorities Matrix,"P0–P3 criteria, coverage targets, execution ordering","testing,prioritization,risk",core,knowledge/test-priorities-matrix.md
+test-healing-patterns,Test Healing Patterns,"Common failure patterns and automated fixes","healing,debugging,patterns",core,knowledge/test-healing-patterns.md
+selector-resilience,Selector Resilience,"Robust selector strategies and debugging techniques","selectors,locators,debugging,ui",core,knowledge/selector-resilience.md
+timing-debugging,Timing Debugging,"Race condition identification, deterministic wait fixes, wall-clock fixtures and fake timers, and unawaited promises in test bodies","timing,async,debugging,clock,fake-timers,expiry,ttl,unawaited,await,floating-promise",extended,knowledge/timing-debugging.md
+overview,Playwright Utils Overview,"Installation, design principles, fixture patterns for API and UI testing","playwright-utils,fixtures,api,backend,ui",core,knowledge/overview.md
+playwright-utils-mandate,Playwright Utils Mandate,"Binding rule when tea_use_playwright_utils is true: substitution table (page.route to interceptNetworkCall, raw request to apiRequest, waitForTimeout to recurse), REQUIRED vs RECOMMENDED levels, banned patterns, pre-emit self-check, deviation protocol","playwright-utils,standards,generation,review,governance,mandate",core,knowledge/playwright-utils-mandate.md
+api-request,API Request,"Typed HTTP client, schema validation, retry logic, operation-based overload for API and service testing","api,backend,service-testing,api-testing,playwright-utils,openapi,codegen,operation",core,knowledge/api-request.md
+network-recorder,Network Recorder,"HAR record/playback, CRUD detection for offline UI testing","network,playwright-utils,ui,har",extended,knowledge/network-recorder.md
+auth-session,Auth Session,"Token persistence, multi-user, API and browser authentication","auth,playwright-utils,api,backend,jwt,token",core,knowledge/auth-session.md
+intercept-network-call,Intercept Network Call,"Network spy/stub, JSON parsing for UI tests","network,playwright-utils,ui",extended,knowledge/intercept-network-call.md
+recurse,Recurse Polling,"Async polling for API responses, background jobs, eventual consistency","polling,playwright-utils,api,backend,async,eventual-consistency",extended,knowledge/recurse.md
+log,Log Utility,"Report logging, structured output for API and UI tests","logging,playwright-utils,api,ui",extended,knowledge/log.md
+file-utils,File Utilities,"CSV/XLSX/PDF/ZIP validation for API exports and UI downloads","files,playwright-utils,api,backend,ui",extended,knowledge/file-utils.md
+burn-in,Burn-in Runner,"Smart test selection, git diff for CI optimization","ci,playwright-utils",extended,knowledge/burn-in.md
+network-error-monitor,Network Error Monitor,"HTTP 4xx/5xx detection for UI tests","monitoring,playwright-utils,ui",extended,knowledge/network-error-monitor.md
+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-mandate,Pact.js Utils Mandate,"Binding rule when tea_use_pactjs_utils is true: substitution table (hand-cast given to createProviderState, literal VerifierOptions to buildVerifierOptions, bespoke auth middleware to createRequestFilter), relevance gate before scaffolding, banned patterns, pre-emit self-check, broker degradation","pactjs-utils,contract-testing,pact,standards,generation,review,governance,mandate",core,knowledge/pactjs-utils-mandate.md
+pactjs-utils-zod-to-pact,Pact.js Utils Zod to Pact,"zodToPactMatchers for consumer-curated schemas, example precedence, Pact V3 matcher mapping, and anti-patterns","pactjs-utils,zod,contract-testing,pact,consumer,schema,matchers,api",specialized,knowledge/pactjs-utils-zod-to-pact.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 with fileParallelism:false + pool:forks + singleFork:true (FFI safety), one-file-per-consumer+provider-pair rule (FFI handle collision prevention), jq-normalized publishing, 1:1 local/CI parity, PactV4 patterns","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts,jq,pactv4,ffi,file-organization,one-file-per-pair",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 evidence audit","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
+confidence-gate,Confidence Gate,"1-10 confidence scoring with stop-and-ask rule below threshold for selectors, endpoints, risk classification, fixtures, schemas, and data factories — prevents agent fabrication","reliability,agent-safety,generation,quality,governance",core,knowledge/confidence-gate.md
+maestro-flows,Maestro Flow Patterns,"Declarative mobile flow structure, selector hierarchy (id > text > scoped text), clearState isolation, synchronization without sleeps, subflow composition, text selectors as whole-element regex, taps that report COMPLETED without being handled, visible meaning inside the viewport, asserting the transition rather than a state that may already hold, anti-patterns","mobile,maestro,ios,android,flows,selectors,ui",specialized,knowledge/maestro-flows.md
+mobile-test-strategy,Mobile Test Strategy,"Mobile test level framework (unit/component/contract/device flow), what belongs in a device flow, mobile risk categories (permissions, lifecycle, connectivity, fragmentation, upgrade), device matrix with a gate profile matching local, CI shape, no live third-party flag evaluation in the run path","mobile,maestro,strategy,risk,levels,ci,ios,android",specialized,knowledge/mobile-test-strategy.md
+evidence-integrity,Evidence Integrity,"Falsifiability of checks (hollow green, optional assertions, continue-on-error, partial manifests, assertions already true before the action), three-state diagnostics (pass/fail/could-not-measure), probes that issue the client's own request, verifying the outcome rather than the act, verifying framework properties before use, proving claims from the side that can observe them, environment asymmetry including screen geometry and accumulated credentials, ranking hypotheses by the cost of the measurement that kills them, recording what a change did rather than what it was for","quality,evidence,diagnostics,review,ci,gates,falsifiability",core,knowledge/evidence-integrity.md
+mobile-ci-device-lab,Mobile CI Device Lab,"Build artifact selection (release build vs development shell vs debug-variant development build), native modules that degrade silently in a shell, deep links reachable through the shell routed URL form, development-server manifest signing in non-interactive CI, one device profile across local and CI, Android emulator snapshot caching and config.ini pitfalls, repairing locally created AVDs, per-device identity for sharded runs, runner version pinning, artifact layout and failure diagnosis, sharding measured on wall clock","mobile,maestro,ci,android,ios,expo,emulator,artifacts",specialized,knowledge/mobile-ci-device-lab.md

package/src/module-help.csv

@@ -0,0 +1,11 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+Test Architecture Enterprise,_meta,,,,,,,,,false,https://cordya-ai.github.io/froid-plane-test-architecture-enterprise/llms.txt,
+Test Architecture Enterprise,froid-teach-me-testing,Teach Me Testing,TMT,Teach testing fundamentals through 7 sessions (TEA Academy).,,,0-learning,,,false,test_artifacts,progress file|session notes|completion summary
+Test Architecture Enterprise,froid-testarch-test-design,Test Design,TD,Risk-based test planning.,,,3-solutioning,,froid-testarch-framework,false,test_artifacts,test design document
+Test Architecture Enterprise,froid-testarch-framework,Test Framework,TF,Initialize production-ready test framework.,,,3-solutioning,froid-testarch-test-design,froid-testarch-ci,false,test_artifacts,framework scaffold
+Test Architecture Enterprise,froid-testarch-ci,CI Setup,CI,Configure CI/CD quality pipeline.,,,3-solutioning,froid-testarch-framework,,false,test_artifacts,ci config
+Test Architecture Enterprise,froid-testarch-atdd,ATDD,AT,Generate red-phase acceptance test scaffolds before implementation.,,,4-implementation,froid-create-story:create,froid-dev-story,false,test_artifacts,atdd-checklist|red-phase acceptance tests
+Test Architecture Enterprise,froid-testarch-automate,Test Automation,TA,Expand test coverage.,,,4-implementation,froid-testarch-atdd,,false,test_artifacts,test suite
+Test Architecture Enterprise,froid-testarch-test-review,Test Review,RV,Quality audit (0-100 scoring).,,,4-implementation,froid-testarch-automate,,false,test_artifacts,review report
+Test Architecture Enterprise,froid-testarch-nfr,NFR Evidence Audit,NR,Audit non-functional requirement evidence.,,,4-implementation,froid-testarch-automate,,false,test_artifacts,nfr report
+Test Architecture Enterprise,froid-testarch-trace,Traceability,TR,Coverage traceability and gate.,,,4-implementation,froid-testarch-test-review,,false,test_artifacts,traceability matrix|gate decision

package/src/module.yaml

@@ -0,0 +1,332 @@
+code: tea
+name: "Test Architect"
+header: "Test Architect: quality strategy, automation, and release gates"
+subheader: "Stack-neutral risk, traceability, and release-gate workflows for Froid Plane/Enterprise, with stack-specific execution for web, API, contract, mobile native (Maestro), and backend test suites"
+description: "Master Test Architect for quality strategy, test automation, and release gates"
+default_selected: false
+
+agents:
+  - code: froid-tea
+    name: Murat
+    title: Master Test Architect and Quality Advisor
+    icon: "🧪"
+    description: "Risk-based testing strategy, fixture architecture, ATDD, API and UI automation (Playwright, Cypress, pytest, JUnit, Go test, xUnit, RSpec), mobile native automation (Maestro), consumer-driven contract testing (Pact), and performance/load/chaos testing (k6). Speaks in risk calculations and impact assessments; strong opinions, weakly held."
+    team: software-development
+
+# Variables from Core Config inserted automatically by installer:
+## user_name
+## communication_language
+## document_output_language
+## output_folder
+## project_root
+
+# TEA-specific configuration variables
+# IMPORTANT: tea_use_playwright_utils, tea_use_pactjs_utils, tea_pact_mcp, tea_browser_automation,
+# tea_execution_mode, tea_capability_probe, test_stack_type, ci_platform,
+# and test_framework are ACTIVELY USED in workflows
+# Other variables are FUTURE placeholders for Phase 10 enhancements
+
+test_artifacts:
+  prompt: "Where should test artifacts be stored? (test plans, coverage reports, quality audits)"
+  default: "{output_folder}/test-artifacts"
+  result: "{project-root}/{value}"
+
+# ✅ ACTIVELY USED - Playwright Utils integration (referenced in 6 workflows: automate, atdd, framework, test-design, test-review, ci)
+# CRITICAL: Must be boolean (true/false) not string - workflows check "if config.tea_use_playwright_utils: true"
+# When true, playwright-utils-mandate.md binds generation and review: the package is the default
+# implementation for what it covers, not an option the user has to ask for by name.
+tea_use_playwright_utils:
+  prompt: "Enable Playwright Utils integration?"
+  default: true
+  result: "{value}"
+  single-select:
+    - value: true
+      label: "Yes - Use production utilities (Recommended)"
+    - value: false
+      label: "No - Generate from scratch"
+
+# ✅ ACTIVELY USED - Pact.js Utils integration for contract testing (referenced in workflows: automate, atdd, framework, test-design, test-review, ci)
+# CRITICAL: Must be boolean (true/false) not string - workflows check "if config.tea_use_pactjs_utils: true"
+# When true, pactjs-utils-mandate.md binds any Pact suite TEA writes. It does NOT mean every project
+# gets contract tests: the mandate's relevance gate still requires a real consumer-provider boundary.
+tea_use_pactjs_utils:
+  prompt: "Enable Pact.js Utils for consumer-driven contract testing?"
+  default: true
+  result: "{value}"
+  single-select:
+    - value: true
+      label: "Yes - Use production utilities when contract tests are written (Recommended)"
+    - value: false
+      label: "No - Generate raw Pact from scratch"
+
+# ✅ ACTIVELY USED - Pact MCP integration for broker interaction during contract testing
+# Controls how TEA interacts with PactFlow/Pact Broker during test generation and review
+# CRITICAL: Must be a string value: "mcp" | "none"
+# Default "mcp" is safe without a broker: every broker-dependent step degrades per pact-mcp.md when the
+# MCP tools are unreachable (falls back to provider source or OpenAPI, reports it, and continues).
+tea_pact_mcp:
+  prompt: "Enable SmartBear MCP for PactFlow/Pact Broker? Used when a broker is reachable; skipped automatically when it is not."
+  default: "mcp"
+  result: "{value}"
+  single-select:
+    - value: "mcp"
+      label: "Yes - Use the broker when it is reachable (Recommended)"
+    - value: "none"
+      label: "No - Never attempt broker/MCP integration"
+
+# ✅ ACTIVELY USED - Browser automation strategy for TEA workflows
+# Controls how TEA interacts with live browsers during test generation
+# CRITICAL: Must be a string value: "auto" | "cli" | "mcp" | "none"
+tea_browser_automation:
+  prompt: "How should TEA interact with browsers during test generation?"
+  default: "auto"
+  result: "{value}"
+  single-select:
+    - value: "auto"
+      label: "Auto - Smart selection (Recommended)"
+    - value: "cli"
+      label: "CLI only - Playwright CLI (@playwright/cli)"
+    - value: "mcp"
+      label: "MCP only - Playwright MCP servers"
+    - value: "none"
+      label: "None - No live browser interaction"
+
+# ✅ ACTIVELY USED - Orchestration strategy for workflow execution
+# Controls whether TEA runs orchestration steps sequentially, with subagents, or with agent teams
+# CRITICAL: Must be a string value: "auto" | "subagent" | "agent-team" | "sequential"
+tea_execution_mode:
+  prompt: "How should TEA orchestrate multi-step generation and evaluation?"
+  default: "auto"
+  result: "{value}"
+  single-select:
+    - value: "auto"
+      label: "Auto - Probe capabilities and pick best mode (Recommended)"
+    - value: "subagent"
+      label: "Subagent workers - Isolated parallel workers only"
+    - value: "agent-team"
+      label: "Agent Team - Team/delegate mode when available"
+    - value: "sequential"
+      label: "Sequential - Deterministic single-threaded execution"
+
+# ✅ ACTIVELY USED - Probe runtime capabilities before selecting execution mode
+# When true, TEA checks whether subagent/agent-team execution is actually supported and falls back safely.
+tea_capability_probe:
+  prompt: "Probe runtime capabilities before selecting execution mode?"
+  default: true
+  result: "{value}"
+  single-select:
+    - value: true
+      label: "Yes - Probe and fallback automatically (Recommended)"
+    - value: false
+      label: "No - Honor configured mode strictly"
+
+# ✅ ACTIVELY USED - Stack type detection for multi-framework support
+test_stack_type:
+  prompt: "What type of project is this?"
+  default: "auto"
+  result: "{value}"
+  single-select:
+    - value: "auto"
+      label: "Auto-detect from project files (Recommended)"
+    - value: "frontend"
+      label: "Frontend (Node.js, React, Vue, Angular)"
+    - value: "backend"
+      label: "Backend (Python, Java, Go, .NET, Rust)"
+    - value: "fullstack"
+      label: "Full-stack (both frontend and backend)"
+    - value: "mobile"
+      label: "Mobile native (iOS, Android, React Native, Flutter)"
+
+# ✅ ACTIVELY USED - CI/CD platform detection
+ci_platform:
+  prompt: "Which CI/CD platform do you use?"
+  default: "auto"
+  result: "{value}"
+  single-select:
+    - value: "auto"
+      label: "Auto-detect from repository (Recommended)"
+    - value: "github-actions"
+      label: "GitHub Actions"
+    - value: "gitlab-ci"
+      label: "GitLab CI"
+    - value: "jenkins"
+      label: "Jenkins"
+    - value: "azure-devops"
+      label: "Azure DevOps Pipelines"
+    - value: "harness"
+      label: "Harness CI"
+    - value: "circle-ci"
+      label: "CircleCI"
+    - value: "other"
+      label: "Other/Custom"
+
+# ✅ ACTIVELY USED - Test framework selection for multi-stack support
+test_framework:
+  prompt: "Which test framework are you using?"
+  default: "auto"
+  result: "{value}"
+  single-select:
+    - value: "auto"
+      label: "Auto-detect from project files (Recommended)"
+    - value: "playwright"
+      label: "Playwright (JavaScript/TypeScript)"
+    - value: "cypress"
+      label: "Cypress (JavaScript/TypeScript)"
+    - value: "jest"
+      label: "Jest (JavaScript/TypeScript)"
+    - value: "vitest"
+      label: "Vitest (JavaScript/TypeScript)"
+    - value: "pytest"
+      label: "pytest (Python)"
+    - value: "junit"
+      label: "JUnit (Java/Kotlin)"
+    - value: "go-test"
+      label: "Go test (Go)"
+    - value: "dotnet-test"
+      label: "dotnet test (C#/.NET)"
+    - value: "rspec"
+      label: "RSpec (Ruby)"
+    - value: "maestro"
+      label: "Maestro (mobile native: iOS/Android)"
+    - value: "other"
+      label: "Other/Custom"
+
+# ⏭️ FUTURE - Risk threshold (not currently used in test-design workflow, marked for Phase 10)
+risk_threshold:
+  prompt: "What risk level requires mandatory testing?"
+  default: "p1"
+  result: "{value}"
+  single-select:
+    - value: "p0"
+      label: "P0 only (Critical systems)"
+    - value: "p1"
+      label: "P1+ (High & Critical)"
+    - value: "p2"
+      label: "P2+ (Medium, High & Critical)"
+    - value: "p3"
+      label: "All (P0-P3)"
+
+# ⏭️ FUTURE - Test output folders (not currently wired into workflows, marked for Phase 10)
+# IMPORTANT: test_artifacts already resolves to {project-root}/..., so don't re-prepend {project-root}
+test_design_output:
+  prompt: "Where should test design documents be stored?"
+  default: "test-design"
+  result: "{test_artifacts}/{value}"
+
+test_review_output:
+  prompt: "Where should test review reports be stored?"
+  default: "test-reviews"
+  result: "{test_artifacts}/{value}"
+
+trace_output:
+  prompt: "Where should traceability reports be stored?"
+  default: "traceability"
+  result: "{test_artifacts}/{value}"
+
+post-install-notes:
+  test_stack_type:
+    auto: |
+      Stack Auto-Detection:
+        TEA will detect your project type from manifest files:
+        - Frontend: package.json with react/vue/angular, playwright.config.*, vite.config.*
+        - Backend: pyproject.toml, pom.xml, go.mod, *.csproj, Gemfile, Cargo.toml
+        - Mobile: .maestro/ or maestro/ flows, app.json with expo/react-native, Podfile,
+          android/app/build.gradle, *.xcodeproj, pubspec.yaml
+        - Full-stack: both frontend and backend indicators present
+        Mobile is checked before frontend, because a React Native project carries
+        package.json with react and would otherwise misdetect as a web frontend.
+        Projects with mobile indicators are classified as Mobile even when test_stack_type is auto, while preserving the existing frontend behavior for projects without those indicators.
+  ci_platform:
+    auto: |
+      CI Platform Auto-Detection:
+        TEA will detect your CI platform from repository files:
+        - GitHub Actions: .github/workflows/
+        - GitLab CI: .gitlab-ci.yml
+        - Jenkins: Jenkinsfile
+        - Azure DevOps: azure-pipelines.yml
+        - Harness: .harness/
+        - CircleCI: .circleci/config.yml
+        Existing installations without ci_platform default to "auto".
+  tea_browser_automation:
+    cli: |
+      Playwright CLI Setup:
+        npm install -g @playwright/cli@latest
+        playwright-cli install --skills    # Run from project root
+        Node.js 18+ required.
+    mcp: |
+      Playwright MCP Setup (two servers):
+        1. playwright    — npx @playwright/mcp@latest
+        2. playwright-test — npx playwright run-test-mcp-server
+        Configure both MCP servers in your IDE settings.
+        See: https://github.com/microsoft/playwright-mcp
+    auto: |
+      Playwright CLI Setup:
+        npm install -g @playwright/cli@latest
+        playwright-cli install --skills    # Run from project root
+        Node.js 18+ required.
+
+      Playwright MCP Setup (two servers):
+        1. playwright    — npx @playwright/mcp@latest
+        2. playwright-test — npx playwright run-test-mcp-server
+        Configure both MCP servers in your IDE settings.
+        See: https://github.com/microsoft/playwright-mcp
+
+  tea_execution_mode:
+    auto: |
+      Execution Mode (Auto):
+        TEA probes runtime capabilities at orchestration steps.
+        Selection order:
+          1. agent-team (if supported)
+          2. subagent (if supported)
+          3. sequential (fallback)
+        This keeps behavior portable across Codex, Claude Code, and other runtimes.
+    subagent: |
+      Execution Mode (Subagent):
+        TEA will prefer isolated subagent workers for parallel orchestration.
+        If capability probing is enabled and subagent support is unavailable, TEA falls back safely.
+    agent-team: |
+      Execution Mode (Agent Team):
+        TEA will prefer team/delegation orchestration when runtime supports it.
+        If capability probing is enabled and agent-team support is unavailable, TEA falls back safely.
+    sequential: |
+      Execution Mode (Sequential):
+        TEA disables parallel orchestration and runs worker steps one by one.
+        Useful for deterministic debugging and constrained environments.
+
+  tea_use_playwright_utils:
+    true: |
+      Playwright Utils Setup:
+        npm install -D @seontechnologies/playwright-utils
+        Peer dependency: @playwright/test >= 1.54.1
+        Optional, for schema validation: ajv >= 8.0.0, zod >= 3.0.0
+        The flag is binding once set: TEA generates against these utilities by default
+        and flags a hand-rolled equivalent that carries no stated reason. The mandate
+        only applies once the package is installed, so run the framework workflow (TF)
+        or the install above before expecting it to take effect.
+        Docs: https://seontechnologies.github.io/playwright-utils/
+  tea_use_pactjs_utils:
+    true: |
+      Pact.js Utils Setup:
+        npm install -D @seontechnologies/pactjs-utils
+        Peer dependency: @pact-foundation/pact >= 16.2.0
+          npm install -D @pact-foundation/pact
+        For remote flow (with Pact Broker):
+          Set PACT_BROKER_BASE_URL and PACT_BROKER_TOKEN as env vars or CI secrets.
+          Also set GITHUB_SHA (auto-set by GitHub Actions) and GITHUB_BRANCH (must be defined explicitly: ${{ github.head_ref || github.ref_name }}).
+        For local flow (monorepo):
+          No broker needed - consumer generates pacts, provider verifies locally.
+        Docs: https://seontechnologies.github.io/pactjs-utils/
+  tea_pact_mcp:
+    mcp: |
+      SmartBear MCP Setup (PactFlow integration):
+        Install: npm install -g @smartbear/mcp
+        Claude Code (global): claude mcp add-json -s user smartbear '{"type":"stdio","command":"npx","args":["-y","@smartbear/mcp@latest"],"env":{"PACT_BROKER_BASE_URL":"https://{tenant}.pactflow.io","PACT_BROKER_TOKEN":"<your-api-token>"}}'
+        Required env vars:
+          PACT_BROKER_BASE_URL=https://{tenant}.pactflow.io
+          PACT_BROKER_TOKEN=<your-api-token>
+        Requires: Node.js 20+
+        Docs: https://developer.smartbear.com/smartbear-mcp/docs/getting-started
+
+# Directories to create during installation (declarative, no code execution)
+directories:
+  - "{test_artifacts}"