froid-plane-test-architecture-enterprise 1.23.4

package/src/workflows/testarch/froid-testarch-test-design/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/workflows/testarch/froid-testarch-test-design/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/workflows/testarch/froid-testarch-test-design/resources/test-design-epic-3.example.md

@@ -0,0 +1,300 @@
+---
+runScope: 'epic-level'
+runKey: 'epic-3-team-invitations'
+workflowStatus: 'completed'
+totalSteps: 5
+stepsCompleted:
+  ['step-01-detect-mode', 'step-02-load-context', 'step-03-risk-and-testability', 'step-04-coverage-plan', 'step-05-generate-output']
+lastStep: 'step-05-generate-output'
+nextStep: ''
+lastSaved: '2026-08-17'
+---
+
+# Test Design: Epic 3: Team Invitations and Role Changes
+
+**Date:** 2026-08-17
+**Author:** Priya Nair
+**Status:** Draft for approval
+
+## Executive Summary
+
+**Scope:** Epic-level test design for inviting members, accepting invitations, changing roles, and recording the resulting audit events.
+
+**Risk Summary:**
+
+- Total risks identified: 7
+- High risks with score 6 or greater: 3
+- Critical categories: Security, Data Integrity, Business Impact
+
+**Coverage Summary:**
+
+- P0: 4 scenarios
+- P1: 6 scenarios
+- P2: 5 scenarios
+- P3: 2 scenarios
+- Total: 17 scenarios, estimated at 41 to 63 hours across 1.5 to 2.5 weeks
+
+Risk score determines the required governance action. Test priority is assigned separately from business criticality, user impact, workaround availability, and execution value. For example, R-005 scores 3 while its audit-event scenario is P1 because missing actor and role history has compliance impact; the score does not hold it at P2 or P3 automatically.
+
+## Not in Scope
+
+| Item                          | Reasoning                                                                            | Mitigation                                                                           |
+| ----------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
+| SCIM provisioning             | Owned by Epic 7 and uses a separate identity-provider contract                       | Keep existing SCIM regression suite required on release branches                     |
+| Billing seat reconciliation   | The invitation flow emits a membership event; billing consumption is owned by Epic 4 | Contract-test the event schema here and trace billing behavior in Epic 4             |
+| Email provider deliverability | Provider-level inbox placement is outside application control                        | Validate accepted request, template payload, retry behavior, and provider receipt ID |
+
+## Risk Assessment
+
+### High Risks: Score 6 or Greater
+
+| Risk ID | Category | Description                                                                                | Probability | Impact | Score | Mitigation                                                                                  | Owner           | Timeline                       |
+| ------- | -------- | ------------------------------------------------------------------------------------------ | ----------: | -----: | ----: | ------------------------------------------------------------------------------------------- | --------------- | ------------------------------ |
+| R-001   | SEC      | A project administrator can grant Owner privileges or change a member outside their tenant |           3 |      3 |     9 | Enforce tenant-scoped authorization and an immutable Owner policy at the API boundary       | Identity team   | Before implementation complete |
+| R-002   | DATA     | Retrying an invitation acceptance creates two memberships or consumes two seats            |           2 |      3 |     6 | Use invitation-token idempotency and a unique tenant-user membership constraint             | Membership team | Before API tests activate      |
+| R-003   | BUS      | An expired or revoked invitation remains usable                                            |           2 |      3 |     6 | Validate status and expiry in the acceptance transaction, then consume the token atomically | Membership team | Before implementation complete |
+
+### Medium Risks: Score 3 to 4
+
+| Risk ID | Category | Description                                                             | Probability | Impact | Score | Mitigation                                                      | Owner           |
+| ------- | -------- | ----------------------------------------------------------------------- | ----------: | -----: | ----: | --------------------------------------------------------------- | --------------- |
+| R-004   | OPS      | Email-provider retries send duplicate invitation messages               |           2 |      2 |     4 | Persist the provider receipt and deduplicate by invitation ID   | Platform team   |
+| R-005   | DATA     | Audit records omit the actor, old role, or new role                     |           1 |      3 |     3 | Emit the audit event in the same transaction as the role update | Membership team |
+| R-007   | PERF     | Bulk invitation creation exceeds the accepted latency or throughput SLO |           2 |      2 |     4 | Define the SLO, then validate it at the approved concurrency    | Platform team   |
+
+### Low Risks: Score 1 to 2
+
+| Risk ID | Category | Description                                                       | Probability | Impact | Score | Action                                       |
+| ------- | -------- | ----------------------------------------------------------------- | ----------: | -----: | ----: | -------------------------------------------- |
+| R-006   | BUS      | A long display name wraps poorly in the pending-invitations table |           1 |      2 |     2 | Monitor and cover with a component edge case |
+
+### Risk Category Legend
+
+- **TECH**: Technical or architecture risk
+- **SEC**: Security and authorization risk
+- **PERF**: Performance and resource risk
+- **DATA**: Data integrity and consistency risk
+- **BUS**: Business and user-impact risk
+- **OPS**: Deployment, configuration, and operational risk
+
+## NFR Planning
+
+This plan names future evidence. Final PASS, CONCERNS, and FAIL decisions belong to `nfr-assess` after implementation evidence exists.
+
+| NFR Domain      | Requirement or Threshold                                                                                    | Risk Link    | Planned Validation                                         | Evidence Needed                    |
+| --------------- | ----------------------------------------------------------------------------------------------------------- | ------------ | ---------------------------------------------------------- | ---------------------------------- |
+| Security        | Tenant isolation on every invitation and role endpoint; Owner privilege cannot be granted through this epic | R-001        | API authorization matrix plus denied cross-tenant E2E path | API report, E2E trace, SAST report |
+| Performance     | UNKNOWN: no accepted latency or throughput threshold exists for bulk invitation creation                    | R-007        | Clarify SLO, then run k6 at the approved concurrency       | Approved SLO and k6 report         |
+| Reliability     | Provider retry must create one logical invitation and at most one membership                                | R-002, R-004 | API idempotency tests and 10-iteration burn-in             | JUnit results and burn-in report   |
+| Maintainability | Membership module line coverage at least 80%; no duplicated role-policy implementation                      | R-001, R-005 | Coverage report and static duplication analysis            | LCOV and duplication report        |
+
+**Unknown thresholds:** Bulk invitation latency and throughput. Product and Platform must agree on the SLO before performance evidence can be scored.
+
+## Entry Criteria
+
+- [ ] Acceptance criteria and role matrix approved by Product, Identity, and Membership owners
+- [ ] Tenant and membership factories support automatic cleanup
+- [ ] Email provider stub exposes deterministic success and retry outcomes
+- [ ] Test environment has two isolated tenants and seeded Owner accounts
+- [ ] R-001 authorization policy implemented before its P0 tests are activated
+
+## Exit Criteria
+
+- [ ] All P0 tests pass
+- [ ] P1 pass rate is at least 95%, with failures triaged
+- [ ] No open critical or high-severity defect
+- [ ] Every score-6-or-greater mitigation is complete or has a stakeholder-approved waiver
+- [ ] Evidence source identified for each of the four NFR domains
+
+## Test Coverage Plan
+
+P0, P1, P2, and P3 describe priority. Execution timing is defined separately below. Risk score is a supporting signal and never assigns priority by itself.
+
+### P0: Critical
+
+**Criteria:** The scenario protects a core authorization or membership-integrity path, has no safe workaround, and a failure would block release.
+
+| Test ID   | Requirement                                                | Test Level | Risk Link    | Notes                            |
+| --------- | ---------------------------------------------------------- | ---------- | ------------ | -------------------------------- |
+| 3-API-001 | Reject a role change for a member in another tenant        | API        | R-001        | Direct tenant-boundary proof     |
+| 3-API-002 | Reject granting Owner through the role-change endpoint     | API        | R-001        | Immutable Owner policy           |
+| 3-API-003 | Accepting the same invitation twice creates one membership | API        | R-002        | Concurrent duplicate submissions |
+| 3-E2E-001 | Invited member accepts once and enters the correct tenant  | E2E        | R-002, R-003 | Core user journey                |
+
+**Total P0:** 4 scenarios, about 14 to 20 hours
+
+### P1: High
+
+**Criteria:** Important common workflows, integration boundaries, and high-impact error handling with a workable recovery path.
+
+| Test ID    | Requirement                                                  | Test Level  | Risk Link | Notes                          |
+| ---------- | ------------------------------------------------------------ | ----------- | --------- | ------------------------------ |
+| 3-E2E-002  | Administrator invites a new Member and sees Pending status   | E2E         | R-004     | One browser happy path         |
+| 3-API-004  | Reject an expired invitation token                           | API         | R-003     | Boundary time fixed by fixture |
+| 3-API-005  | Reject a revoked invitation token                            | API         | R-003     | No membership created          |
+| 3-API-006  | Retry after provider timeout returns the original invitation | API         | R-004     | Idempotency by invitation ID   |
+| 3-INT-001  | Role update emits actor, tenant, old role, and new role      | Integration | R-005     | Audit event contract           |
+| 3-COMP-001 | Role selector hides Owner and disables the current Owner     | Component   | R-001     | User-level interaction API     |
+
+**Total P1:** 6 scenarios, about 16 to 24 hours
+
+### P2: Medium
+
+**Criteria:** Secondary workflows and bounded edge cases whose failure has a practical workaround.
+
+| Test ID    | Requirement                                                | Test Level | Risk Link | Notes                              |
+| ---------- | ---------------------------------------------------------- | ---------- | --------- | ---------------------------------- |
+| 3-API-007  | Cancel a pending invitation                                | API        | R-003     | Subsequent acceptance rejected     |
+| 3-API-008  | Resend reuses the logical invitation and rotates the token | API        | R-004     | Old token becomes invalid          |
+| 3-COMP-002 | Invalid email displays field-level guidance                | Component  | None      | Atomic validation behavior         |
+| 3-COMP-003 | Pending invitation table handles long names                | Component  | R-006     | Layout at supported small viewport |
+| 3-UNIT-001 | Invitation expiry comparison handles the exact boundary    | Unit       | R-003     | Fake clock, no wall-clock wait     |
+
+**Total P2:** 5 scenarios, about 8 to 14 hours
+
+### P3: Low
+
+**Criteria:** Exploratory checks and benchmarks that inform future optimization.
+
+| Test ID    | Requirement                                   | Test Level  | Risk Link | Notes                                   |
+| ---------- | --------------------------------------------- | ----------- | --------- | --------------------------------------- |
+| 3-EXP-001  | Keyboard-only review of the invitation dialog | Exploratory | None      | Record accessibility observations       |
+| 3-PERF-001 | Establish a provisional bulk-invite baseline  | Performance | R-007     | Informational until the SLO is approved |
+
+**Total P3:** 2 scenarios, about 3 to 5 hours
+
+## Execution Strategy
+
+**Philosophy:** Run every functional scenario in pull requests when the suite remains below 15 minutes. Defer only work with material infrastructure or duration cost.
+
+- **Pull request:** All API, E2E, integration, component, and unit scenarios. Playwright runs in parallel with a target duration below 15 minutes.
+- **Nightly:** Ten-iteration idempotency burn-in and email-provider retry suite.
+- **Weekly:** Provisional k6 baseline and keyboard-only exploratory session.
+
+## Resource Estimates
+
+| Priority  | Scenarios | Estimate           | Complexity Drivers                               |
+| --------- | --------: | ------------------ | ------------------------------------------------ |
+| P0        |         4 | 14 to 20 hours     | Two-tenant setup, concurrency, authorization     |
+| P1        |         6 | 16 to 24 hours     | Provider stub, audit event capture, browser path |
+| P2        |         5 | 8 to 14 hours      | Boundary fixtures and component states           |
+| P3        |         2 | 3 to 5 hours       | Benchmark setup and exploratory recording        |
+| **Total** |    **17** | **41 to 63 hours** | **About 1.5 to 2.5 weeks**                       |
+
+### Prerequisites
+
+**Test data:**
+
+- Tenant, user, invitation, and membership factories with override support and automatic cleanup
+- Fixed-time fixture for expiry boundaries
+
+**Tooling:**
+
+- Playwright for API, E2E, and component coverage
+- Vitest for membership-policy unit coverage
+- k6 for the provisional performance baseline
+
+**Environment:**
+
+- Two isolated tenants
+- Server-side email provider stub with retry controls
+- Audit event sink readable by the integration suite
+
+## Quality Gate Criteria
+
+- P0 pass rate: 100%
+- P1 pass rate: at least 95%
+- Overall oracle coverage: at least 80%
+- High-risk mitigations: complete before release or covered by an approved human waiver
+- Security scenarios: 100% passing
+- NFR evidence: source identified for Security, Performance, Reliability, and Maintainability
+- Final NFR status: deferred to `nfr-assess`
+
+## Mitigation Plans
+
+### R-001: Cross-Tenant or Owner Privilege Escalation, Score 9
+
+**Strategy:** Centralize the role policy, enforce tenant scope from the authenticated subject, reject Owner mutation, and log denied attempts.
+**Owner:** Identity team
+**Timeline:** Before implementation complete
+**Status:** In progress
+**Verification:** `3-API-001`, `3-API-002`, and `3-COMP-001`
+
+### R-002: Duplicate Membership on Retried Acceptance, Score 6
+
+**Strategy:** Consume the token and insert membership in one transaction with a unique constraint; return the existing membership on an identical retry.
+**Owner:** Membership team
+**Timeline:** Before API tests activate
+**Status:** Planned
+**Verification:** `3-API-003` under concurrent submission and `3-E2E-001`
+
+### R-003: Expired or Revoked Token Accepted, Score 6
+
+**Strategy:** Lock the invitation row, validate status and expiry, then consume it atomically.
+**Owner:** Membership team
+**Timeline:** Before implementation complete
+**Status:** Planned
+**Verification:** `3-API-004`, `3-API-005`, and `3-UNIT-001`
+
+## Assumptions and Dependencies
+
+### Assumptions
+
+1. The role matrix in `docs/security/team-role-matrix.md` is the approved authority.
+2. Invitation email content is localized by the provider adapter after receiving structured template data.
+3. Audit event delivery is synchronous with the membership transaction.
+
+### Dependencies
+
+1. Identity team publishes the tenant-scope middleware contract before P0 automation starts.
+2. Platform team provides deterministic provider retry controls before nightly automation starts.
+3. Product and Platform approve a bulk-invite SLO before performance can receive a final status.
+
+### Risk to the Plan
+
+- **Risk:** The provider stub cannot reproduce a timeout after accepting a request.
+  - **Impact:** R-004 retry behavior cannot be proved deterministically.
+  - **Contingency:** Add a controllable fault mode to the adapter test server before implementing `3-API-006`.
+
+## Follow-on Workflows
+
+- Run `/froid-testarch-atdd` explicitly for the four P0 scenarios.
+- Run `/froid-testarch-automate` for the remaining functional coverage after implementation exists.
+- Run `/froid-testarch-nfr` when evidence exists for all four NFR domains.
+- Run `/froid-testarch-trace` to map the approved oracle and apply the release gate.
+
+## Approval
+
+- [ ] Product Manager: Elena Ruiz, Date pending
+- [ ] Tech Lead: Marcus Chen, Date pending
+- [ ] QA Lead: Priya Nair, Date pending
+
+## Interworking and Regression
+
+| Service or Component | Impact                                               | Regression Scope                            |
+| -------------------- | ---------------------------------------------------- | ------------------------------------------- |
+| Identity middleware  | Supplies tenant and actor claims                     | Existing tenant-isolation API suite         |
+| Membership service   | Creates memberships and changes roles                | Membership CRUD and unique-constraint tests |
+| Email adapter        | Sends, retries, and deduplicates invitation messages | Provider adapter contract suite             |
+| Audit service        | Records invitations and role changes                 | Audit schema and event-consumer regression  |
+
+## Appendix
+
+### Knowledge Base References
+
+- [risk-governance.md](./knowledge/risk-governance.md)
+- [probability-impact.md](./knowledge/probability-impact.md)
+- [test-levels-framework.md](./knowledge/test-levels-framework.md)
+- [test-priorities-matrix.md](./knowledge/test-priorities-matrix.md)
+- [nfr-criteria.md](./knowledge/nfr-criteria.md)
+
+### Related Documents
+
+- PRD: `docs/prd/collaboration.md`
+- Epic: `docs/epics/epic-3-team-invitations.md`
+- Architecture: `docs/architecture/membership-service.md`
+- Role matrix: `docs/security/team-role-matrix.md`
+
+**Generated by:** Froid TEA Agent, Test Architect Module
+**Workflow:** `froid-testarch-test-design`
+**Version:** 4.0